Products — API Docs | Simple Product Feeds

List products

GET /v1/products

Returns a paginated list of source products from your Shopify catalog.

Required scope: read_products

Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (minimum 1).
`per_page`	integer	`25`	Results per page (maximum 100).
`search`	string	—	Search by SKU, title, price, or product data.
`sort`	string	—	Column name to sort by (e.g., `title`, `sku`, `price`).
`order`	string	`asc`	Sort direction: `asc` or `desc`.
`excluded`	boolean	—	Filter by excluded status.
`has_overrides`	boolean	—	Filter by presence of any override field.
`condition`	string	—	Filter by condition: `new`, `refurbished`, or `used`.

Request

curl "https://app.simpleproductfeeds.com/v1/products?page=1&per_page=10&search=shirt" \
  -H "Authorization: Bearer spf_live_sk_your_key_here"

Response

{
  "data": [
    {
      "id": "prod_1234",
      "object": "product",
      "shopify_product_id": "8012345678901",
      "shopify_variant_id": "44012345678901",
      "sku": "SHIRT-BLU-M",
      "title": "Blue T-Shirt - Medium",
      "price": "29.99",
      "compare_at_price": "39.99",
      "inventory_quantity": 150,
      "image_url": "https://cdn.shopify.com/s/files/1/example/shirt-blue.jpg",
      "vendor": "My Brand",
      "product_type": "Apparel",
      "status": "active",
      "extracted_at": "2026-03-09T12:00:00Z",
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": "2026-03-09T12:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 1482,
    "total_pages": 149,
    "has_more": true
  }
}

Response fields

Field	Type	Description
`id`	string	Unique identifier with prod_ prefix.
`object`	string	Always "product".
`shopify_product_id`	string	The Shopify product ID.
`shopify_variant_id`	string	The Shopify variant ID.
`sku`	string	Product SKU.
`title`	string	Product variant title.
`price`	string \| null	Current price.
`compare_at_price`	string \| null	Compare-at (original) price, if set.
`inventory_quantity`	integer	Available inventory quantity.
`image_url`	string \| null	Primary image URL.
`vendor`	string \| null	Product vendor.
`product_type`	string \| null	Product type.
`status`	string	Product status: "active".
`gtin`	string \| null	GTIN/EAN/UPC barcode override.
`mpn`	string \| null	Manufacturer part number override.
`condition`	string \| null	Product condition: "new", "refurbished", or "used".
`excluded`	boolean	Whether the product is excluded from the feed.
`excluded_reason`	string \| null	Reason for excluding the product.
`custom_labels`	object	Custom label overrides (custom_label_0 through custom_label_4).
`has_overrides`	boolean	Whether any override fields have been set on this product.
`extracted_at`	string	ISO 8601 timestamp when product data was last extracted from Shopify.
`created_at`	string	ISO 8601 timestamp when the product was first imported.
`updated_at`	string	ISO 8601 timestamp when the product was last updated.

Errors

Status	Code	Description
422	`no_feed`	No feed has been configured for this shop. Complete onboarding first.

Get a product

GET /v1/products/:id

Returns a single product by ID.

Required scope: read_products

Request

curl https://app.simpleproductfeeds.com/v1/products/prod_1234 \
  -H "Authorization: Bearer spf_live_sk_your_key_here"

The prod_ prefix is optional — both prod_1234 and 1234 are accepted.

Response

Returns a single product object wrapped in data:

{
  "data": {
    "id": "prod_1234",
    "object": "product",
    "shopify_product_id": "8012345678901",
    "shopify_variant_id": "44012345678901",
    "sku": "SHIRT-BLU-M",
    "title": "Blue T-Shirt - Medium",
    "price": "29.99",
    "compare_at_price": "39.99",
    "inventory_quantity": 150,
    "image_url": "https://cdn.shopify.com/s/files/1/example/shirt-blue.jpg",
    "vendor": "My Brand",
    "product_type": "Apparel",
    "status": "active",
    "extracted_at": "2026-03-09T12:00:00Z",
    "created_at": "2025-06-15T10:00:00Z",
    "updated_at": "2026-03-09T12:00:00Z"
  }
}

Errors

Status	Code	Description
404	`resource_not_found`	No product found with the given ID.

Update a product

PATCH /v1/products/:id

Updates override fields on a product. These overrides are applied to the feed transformation pipeline — overridden values replace source data in the generated feed. Feed rules still have final say and can override or further modify API-set values.

Required scope: write_products

Writable fields

Parameter	Type	Description
`title`	string	Title override (replaces Shopify title in API response).
`description`	string	Description override.
`brand`	string	Brand/vendor override.
`gtin`	string	GTIN/EAN/UPC barcode.
`mpn`	string	Manufacturer part number.
`condition`	string	Product condition: `new`, `refurbished`, or `used`.
`excluded`	boolean	Exclude product from the feed.
`excluded_reason`	string	Reason for exclusion.
`custom_labels`	object	Custom labels (`custom_label_0` through `custom_label_4`).

Request

curl -X PATCH https://app.simpleproductfeeds.com/v1/products/prod_1234 \
  -H "Authorization: Bearer spf_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Premium Blue T-Shirt", "gtin": "1234567890123", "condition": "new"}'

Response

Returns the updated product object wrapped in data.

Errors

Status	Code	Description
404	`resource_not_found`	No product found with the given ID.
422	`invalid_param`	Invalid value for `condition` or `custom_labels`.

Restore a product

POST /v1/products/:id/restore

Clears all override fields, restoring the product to its original Shopify data. This action is idempotent — calling it on a product with no overrides returns success.

Required scope: write_products

Request

curl -X POST https://app.simpleproductfeeds.com/v1/products/prod_1234/restore \
  -H "Authorization: Bearer spf_live_sk_your_key_here"

Response

Returns the restored product object wrapped in data, with all override fields cleared.

Errors

Status	Code	Description
404	`resource_not_found`	No product found with the given ID.

Batch update products

PATCH /v1/products/batch

Updates override fields on multiple products in a single request. Supports partial success — products that fail validation are reported in the errors array while valid products are still updated.

Required scope: write_products

Parameters

Parameter	Type	Required	Description
`products`	array	Yes	Array of product update objects (max 100). Each object must include `id` and any writable fields.

Request

curl -X PATCH https://app.simpleproductfeeds.com/v1/products/batch \
  -H "Authorization: Bearer spf_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {"id": "prod_1234", "title": "Premium Blue T-Shirt", "gtin": "1234567890123"},
      {"id": "prod_5678", "brand": "Custom Brand", "condition": "new"}
    ]
  }'

Response

{
  "data": {
    "updated": ["prod_1234", "prod_5678"],
    "errors": []
  }
}

If some products fail, they appear in errors:

{
  "data": {
    "updated": ["prod_1234"],
    "errors": [
      {"id": "prod_9999", "error": "Product not found."}
    ]
  }
}

A single product.updated webhook is fired for the entire batch, not per item.

Errors

Status	Code	Description
422	`invalid_param`	`products` is not an array.
422	`batch_too_large`	More than 100 items in the batch.

Batch restore products

POST /v1/products/batch/restore

Clears all override fields on multiple products, restoring them to their original Shopify data.

Required scope: write_products

Parameters

Parameter	Type	Required	Description
`ids`	string[]	Yes	Array of product IDs to restore (max 100).

Request

curl -X POST https://app.simpleproductfeeds.com/v1/products/batch/restore \
  -H "Authorization: Bearer spf_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["prod_1234", "prod_5678"]}'

Response

{
  "data": {
    "restored": ["prod_1234", "prod_5678"],
    "errors": []
  }
}

Errors

Status	Code	Description
422	`invalid_param`	`ids` is not an array.
422	`batch_too_large`	More than 100 items in the batch.