Skip to Content
API referenceProducts

Products

Related events: product.created · product.deleted · product.updated · write_back.applied · write_back.rolled_back

Endpoints

The Product object

Attributes

  • idstring

    Unique identifier of the object (prefixed, opaque).

  • objectstring

    product

  • brandstring

    The brand the object belongs to (br_…).

  • sourceenum

    Where a product comes from. Synced sources (Shopify, a CSV / XML feed, later WooCommerce / PrestaShop) are the source of truth: their products are read-only in Skoup and refreshed by the sync. Manual products are fully editable, and so are the offerings read on the brand's site by the site profile (site): a suggestion the customer edits, never overwritten once touched.

    Possible values: shopify · feed · manual · site

  • read_onlyboolean
  • external_idstringnullable

    Identifier at the source (e.g. a Shopify GID), null for manual products.

  • handlestringnullable
  • titlestring
  • descriptionstringnullable
  • vendorstringnullable
  • categorystringnullable
  • skustringnullable
  • gtinstringnullable
  • pricestringnullable

    Decimal string, e.g. "1299.00".

  • currencystringnullable
  • price_periodenumnullable

    What a price buys: a month or a year of a subscription, or the thing once. Shared by the catalogue and by the price an answer states — two prices of different periods are never compared.

    Possible values: month · year · once

  • price_annualstringnullable

    Always the amount of one year, decimal string.

  • price_unitenumnullable

    What a price is counted by: the whole offer, or each user (seat, practitioner, workstation). Shared by the catalogue and by the price an answer states.

    Possible values: flat · per_user

  • addonsarray of object
    Show child attributes
    • namestring
    • pricenumbernullable
    • periodenumnullable

      Possible values: month · year · once

    • unitenumnullable

      Possible values: flat · per_user

  • urlstringnullable
  • image_urlstringnullable
  • statusenum

    Publication status, aligned on Shopify's product statuses so a synced product maps one-to-one.

    Possible values: active · draft · archived

  • tagsarray of string
  • optionsarray of object
    Show child attributes
    • namestring
    • valuesarray of string
  • variantsarray of variants
    Show child attributes
    • idstring

      Unique identifier of the object (prefixed, opaque).

    • objectstring

      variant

    • titlestring
    • skustringnullable
    • gtinstringnullable
    • pricestringnullable
    • compare_at_pricestringnullable
    • inventory_quantityintegernullable
    • optionsarray of object
      Show child attributes
      • namestring
      • valuestring
  • synced_atstringnullable
  • livemodeboolean

    true for live data, false for the test-mode sandbox.

  • createdinteger

    Time at which the object was created (unix timestamp, seconds).

  • updatedstring

    Time at which the object was last updated.

The Product object
{
  "id": "prod_031CQNg2fZXIIClKM3I8uF",
  "object": "product",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "source": "shopify",
  "read_only": true,
  "external_id": "gid://shopify/Product/8123456789012",
  "handle": "grizl-cf-sl-7",
  "title": "Grizl CF SL 7",
  "description": "Gravel carbone, transmission Shimano GRX 2x12.",
  "vendor": "Nordvelo",
  "category": "Vélos gravel",
  "sku": "GRZ-CF-SL7",
  "gtin": "4251234567890",
  "price": "2499.00",
  "currency": "EUR",
  "price_period": null,
  "price_annual": null,
  "price_unit": null,
  "addons": [],
  "url": "https://nordvelo.fr/products/grizl-cf-sl-7",
  "image_url": "https://cdn.shopify.com/s/files/grizl-cf-sl-7.jpg",
  "status": "active",
  "tags": [
    "gravel",
    "carbone"
  ],
  "options": [
    {
      "name": "Taille",
      "values": [
        "S",
        "M",
        "L"
      ]
    }
  ],
  "variants": [
    {
      "id": "var_031CQNtmS3W4oi14CtkFvn",
      "object": "variant",
      "title": "M",
      "sku": "GRZ-CF-SL7-M",
      "gtin": "4251234567891",
      "price": "2499.00",
      "compare_at_price": null,
      "inventory_quantity": 7,
      "options": [
        {
          "name": "Taille",
          "value": "M"
        }
      ]
    }
  ],
  "synced_at": "2026-09-21T03:00:12Z",
  "livemode": true,
  "created": 1790000000,
  "updated": 1790003600
}

The Write back object

Attributes

  • idstring

    Unique identifier of the object (prefixed, opaque).

  • objectstring

    write_back

  • brandstring

    The brand the object belongs to (br_…).

  • productstring
  • taskstringnullable
  • statusenum

    - applied → written in the store; reversible until rollback_until. - rolled_back → the « before » values were written back. - failed → Shopify refused the write, nothing changed at the store.

    Possible values: applied · rolled_back · failed

  • changesarray of object
    Show child attributes
    • fieldenum

      Possible values: description_html · seo_title · seo_description · barcode

    • variant_external_idstringnullable
    • variant_titlestringnullable
    • beforestring
    • afterstring
  • errorstringnullable
  • applied_atstringnullable
  • rollback_untilstringnullable

    Last moment a rollback is possible (in the app); NULL once rolled back or failed.

  • rolled_back_atstringnullable
  • livemodeboolean

    true for live data, false for the test-mode sandbox.

  • createdinteger

    Time at which the object was created (unix timestamp, seconds).

The Write back object
{
  "id": "wb_031CQjcAH6UqepovbzUK6t",
  "object": "write_back",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "product": "prod_031CQNg2fZXIIClKM3I8uF",
  "task": "task_031CQg4La2D4FtcCN87OUU",
  "status": "applied",
  "changes": [
    {
      "field": "seo_description",
      "variant_external_id": null,
      "variant_title": null,
      "before": "",
      "after": "Gravel carbone Shimano GRX 2x12, cadre garanti à vie."
    },
    {
      "field": "barcode",
      "variant_external_id": "gid://shopify/ProductVariant/44123456789",
      "variant_title": "M",
      "before": "",
      "after": "4006381333931"
    }
  ],
  "error": null,
  "applied_at": "2026-09-22T14:05:31Z",
  "rollback_until": "2026-10-22T14:05:31Z",
  "rolled_back_at": null,
  "livemode": true,
  "created": 1790085931
}

The Product perception object

Attributes

  • objectstring

    product_perception

  • productstring
  • marketstring

    Market code (ISO country, e.g. FR).

  • periodstring
  • sheet_versionstring
  • scorestring
  • countsstring
  • by_modelstring
  • attributesstring
  • livemodeboolean

    true for live data, false for the test-mode sandbox.

The Product perception object
{
  "object": "product_perception",
  "product": "prod_034fy4zIfaXW6rtqEz1nHT",
  "market": "FR",
  "period": "90d",
  "sheet_version": "string",
  "score": "string",
  "counts": "string",
  "by_model": "string",
  "attributes": "string",
  "livemode": true
}

Create a product

POST/v1/brands/{brand}/products

Adds a manual product — for stores without a connector. Its vendor defaults to the brand name.

Parameters

  • brandstringrequired

    Brand id (br_…).

  • titlestringrequired
  • descriptionstringnullable
  • categorystringnullable
  • vendorstringnullable
  • skustringnullable
  • gtinstringnullable
  • pricenumbernullable
  • currencystringnullable
  • urlstringnullable
  • image_urlstringnullable
  • statusenum

    Publication status, aligned on Shopify's product statuses so a synced product maps one-to-one.

    Possible values: active · draft · archived

  • tagsarray of stringnullable
  • price_periodenumnullable

    What a price buys: a month or a year of a subscription, or the thing once. Shared by the catalogue and by the price an answer states — two prices of different periods are never compared.

    Possible values: month · year · once

  • price_annualnumbernullable

    Always the amount of one year, whatever the way the site writes it.

  • price_unitenumnullable

    What a price is counted by: the whole offer, or each user (seat, practitioner, workstation). Shared by the catalogue and by the price an answer states.

    Possible values: flat · per_user

  • addonsarray of objectnullable
    Show child attributes
    • namestring
    • pricenumbernullable

      Null = on quote.

    • periodenumnullable

      What a price buys: a month or a year of a subscription, or the thing once. Shared by the catalogue and by the price an answer states — two prices of different periods are never compared.

      Possible values: month · year · once

    • unitenumnullable

      What a price is counted by: the whole offer, or each user (seat, practitioner, workstation). Shared by the catalogue and by the price an answer states.

      Possible values: flat · per_user

Returns

Returns the created product object. Raises an error if something goes wrong.

curl -X POST https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/products \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"title":"Grizl CF SL 7","description":"Rewrite the product copy so the frame warranty is stated."}'
Response
{
  "id": "prod_031CQNg2fZXIIClKM3I8uF",
  "object": "product",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "source": "shopify",
  "read_only": true,
  "external_id": "gid://shopify/Product/8123456789012",
  "handle": "grizl-cf-sl-7",
  "title": "Grizl CF SL 7",
  "description": "Gravel carbone, transmission Shimano GRX 2x12.",
  "vendor": "Nordvelo",
  "category": "Vélos gravel",
  "sku": "GRZ-CF-SL7",
  "gtin": "4251234567890",
  "price": "2499.00",
  "currency": "EUR",
  "price_period": null,
  "price_annual": null,
  "price_unit": null,
  "addons": [],
  "url": "https://nordvelo.fr/products/grizl-cf-sl-7",
  "image_url": "https://cdn.shopify.com/s/files/grizl-cf-sl-7.jpg",
  "status": "active",
  "tags": [
    "gravel",
    "carbone"
  ],
  "options": [
    {
      "name": "Taille",
      "values": [
        "S",
        "M",
        "L"
      ]
    }
  ],
  "variants": [
    {
      "id": "var_031CQNtmS3W4oi14CtkFvn",
      "object": "variant",
      "title": "M",
      "sku": "GRZ-CF-SL7-M",
      "gtin": "4251234567891",
      "price": "2499.00",
      "compare_at_price": null,
      "inventory_quantity": 7,
      "options": [
        {
          "name": "Taille",
          "value": "M"
        }
      ]
    }
  ],
  "synced_at": "2026-09-21T03:00:12Z",
  "livemode": true,
  "created": 1790000000,
  "updated": 1790003600
}

Update a product

PATCH/v1/brands/{brand}/products/{product}

Only manual products can be updated: a synced product is read-only (resource_read_only) — fix it in the store, the next sync brings it.

Parameters

  • brandstringrequired

    Brand id (br_…).

  • productstringrequired

    Product id (prod_…).

  • titlestringrequired
  • descriptionstringnullable
  • categorystringnullable
  • vendorstringnullable
  • skustringnullable
  • gtinstringnullable
  • pricenumbernullable
  • currencystringnullable
  • urlstringnullable
  • image_urlstringnullable
  • statusenum

    Publication status, aligned on Shopify's product statuses so a synced product maps one-to-one.

    Possible values: active · draft · archived

  • tagsarray of stringnullable
  • price_periodenumnullable

    What a price buys: a month or a year of a subscription, or the thing once. Shared by the catalogue and by the price an answer states — two prices of different periods are never compared.

    Possible values: month · year · once

  • price_annualnumbernullable

    Always the amount of one year, whatever the way the site writes it.

  • price_unitenumnullable

    What a price is counted by: the whole offer, or each user (seat, practitioner, workstation). Shared by the catalogue and by the price an answer states.

    Possible values: flat · per_user

  • addonsarray of objectnullable
    Show child attributes
    • namestring
    • pricenumbernullable

      Null = on quote.

    • periodenumnullable

      What a price buys: a month or a year of a subscription, or the thing once. Shared by the catalogue and by the price an answer states — two prices of different periods are never compared.

      Possible values: month · year · once

    • unitenumnullable

      What a price is counted by: the whole offer, or each user (seat, practitioner, workstation). Shared by the catalogue and by the price an answer states.

      Possible values: flat · per_user

Returns

Returns the updated product object. Raises an error if something goes wrong.

curl -X PATCH https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/products/prod_034fy4zIfaXW6rtqEz1nHT \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"title":"Grizl CF SL 7","description":"Rewrite the product copy so the frame warranty is stated."}'
Response
{
  "id": "prod_031CQNg2fZXIIClKM3I8uF",
  "object": "product",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "source": "shopify",
  "read_only": true,
  "external_id": "gid://shopify/Product/8123456789012",
  "handle": "grizl-cf-sl-7",
  "title": "Grizl CF SL 7",
  "description": "Gravel carbone, transmission Shimano GRX 2x12.",
  "vendor": "Nordvelo",
  "category": "Vélos gravel",
  "sku": "GRZ-CF-SL7",
  "gtin": "4251234567890",
  "price": "2499.00",
  "currency": "EUR",
  "price_period": null,
  "price_annual": null,
  "price_unit": null,
  "addons": [],
  "url": "https://nordvelo.fr/products/grizl-cf-sl-7",
  "image_url": "https://cdn.shopify.com/s/files/grizl-cf-sl-7.jpg",
  "status": "active",
  "tags": [
    "gravel",
    "carbone"
  ],
  "options": [
    {
      "name": "Taille",
      "values": [
        "S",
        "M",
        "L"
      ]
    }
  ],
  "variants": [
    {
      "id": "var_031CQNtmS3W4oi14CtkFvn",
      "object": "variant",
      "title": "M",
      "sku": "GRZ-CF-SL7-M",
      "gtin": "4251234567891",
      "price": "2499.00",
      "compare_at_price": null,
      "inventory_quantity": 7,
      "options": [
        {
          "name": "Taille",
          "value": "M"
        }
      ]
    }
  ],
  "synced_at": "2026-09-21T03:00:12Z",
  "livemode": true,
  "created": 1790000000,
  "updated": 1790003600
}

Retrieve a product

GET/v1/brands/{brand}/products/{product}

Parameters

  • brandstringrequired

    Brand id (br_…).

  • productstringrequired

    Product id (prod_…).

Returns

Returns the product object. Raises an error if something goes wrong.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/products/prod_034fy4zIfaXW6rtqEz1nHT \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Response
{
  "id": "prod_031CQNg2fZXIIClKM3I8uF",
  "object": "product",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "source": "shopify",
  "read_only": true,
  "external_id": "gid://shopify/Product/8123456789012",
  "handle": "grizl-cf-sl-7",
  "title": "Grizl CF SL 7",
  "description": "Gravel carbone, transmission Shimano GRX 2x12.",
  "vendor": "Nordvelo",
  "category": "Vélos gravel",
  "sku": "GRZ-CF-SL7",
  "gtin": "4251234567890",
  "price": "2499.00",
  "currency": "EUR",
  "price_period": null,
  "price_annual": null,
  "price_unit": null,
  "addons": [],
  "url": "https://nordvelo.fr/products/grizl-cf-sl-7",
  "image_url": "https://cdn.shopify.com/s/files/grizl-cf-sl-7.jpg",
  "status": "active",
  "tags": [
    "gravel",
    "carbone"
  ],
  "options": [
    {
      "name": "Taille",
      "values": [
        "S",
        "M",
        "L"
      ]
    }
  ],
  "variants": [
    {
      "id": "var_031CQNtmS3W4oi14CtkFvn",
      "object": "variant",
      "title": "M",
      "sku": "GRZ-CF-SL7-M",
      "gtin": "4251234567891",
      "price": "2499.00",
      "compare_at_price": null,
      "inventory_quantity": 7,
      "options": [
        {
          "name": "Taille",
          "value": "M"
        }
      ]
    }
  ],
  "synced_at": "2026-09-21T03:00:12Z",
  "livemode": true,
  "created": 1790000000,
  "updated": 1790003600
}

List products

GET/v1/brands/{brand}/products

The brand’s catalogue, newest first, variants included.

Parameters

  • brandstringrequired

    Brand id (br_…).

  • qstring
  • sourcestring
  • statusstring
  • limitinteger

    Number of objects to return, between 1 and 100 (default 20).

  • starting_afterstring

    Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit product objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/products?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Response
{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/products",
  "has_more": false,
  "data": [
    {
      "id": "prod_031CQNg2fZXIIClKM3I8uF",
      "object": "product",
      "brand": "br_031CQGx2DNM4mxT2CO7BL3",
      "source": "shopify",
      "read_only": true,
      "external_id": "gid://shopify/Product/8123456789012",
      "handle": "grizl-cf-sl-7",
      "title": "Grizl CF SL 7",
      "description": "Gravel carbone, transmission Shimano GRX 2x12.",
      "vendor": "Nordvelo",
      "category": "Vélos gravel",
      "sku": "GRZ-CF-SL7",
      "gtin": "4251234567890",
      "price": "2499.00",
      "currency": "EUR",
      "price_period": null,
      "price_annual": null,
      "price_unit": null,
      "addons": [],
      "url": "https://nordvelo.fr/products/grizl-cf-sl-7",
      "image_url": "https://cdn.shopify.com/s/files/grizl-cf-sl-7.jpg",
      "status": "active",
      "tags": [
        "gravel",
        "carbone"
      ],
      "options": [
        {
          "name": "Taille",
          "values": [
            "S",
            "M",
            "L"
          ]
        }
      ],
      "variants": [
        {
          "id": "var_031CQNtmS3W4oi14CtkFvn",
          "object": "variant",
          "title": "M",
          "sku": "GRZ-CF-SL7-M",
          "gtin": "4251234567891",
          "price": "2499.00",
          "compare_at_price": null,
          "inventory_quantity": 7,
          "options": [
            {
              "name": "Taille",
              "value": "M"
            }
          ]
        }
      ],
      "synced_at": "2026-09-21T03:00:12Z",
      "livemode": true,
      "created": 1790000000,
      "updated": 1790003600
    }
  ]
}

List a product’s write-backs

GET/v1/brands/{brand}/products/{product}/write_backs

What Skoup wrote in the store for this product (copy, SEO fields, variant barcodes), field by field with the value it replaced, newest first. Failed attempts are listed too, with their error.

Parameters

  • brandstringrequired

    Brand id (br_…).

  • productstringrequired

    Product id (prod_…).

  • limitinteger

    Number of objects to return, between 1 and 100 (default 20).

  • starting_afterstring

    Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit write_back objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/products/prod_034fy4zIfaXW6rtqEz1nHT/write_backs?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Response
{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/products/prod_034fy4zIfaXW6rtqEz1nHT/write_backs",
  "has_more": false,
  "data": [
    {
      "id": "wb_031CQjcAH6UqepovbzUK6t",
      "object": "write_back",
      "brand": "br_031CQGx2DNM4mxT2CO7BL3",
      "product": "prod_031CQNg2fZXIIClKM3I8uF",
      "task": "task_031CQg4La2D4FtcCN87OUU",
      "status": "applied",
      "changes": [
        {
          "field": "seo_description",
          "variant_external_id": null,
          "variant_title": null,
          "before": "",
          "after": "Gravel carbone Shimano GRX 2x12, cadre garanti à vie."
        },
        {
          "field": "barcode",
          "variant_external_id": "gid://shopify/ProductVariant/44123456789",
          "variant_title": "M",
          "before": "",
          "after": "4006381333931"
        }
      ],
      "error": null,
      "applied_at": "2026-09-22T14:05:31Z",
      "rollback_until": "2026-10-22T14:05:31Z",
      "rolled_back_at": null,
      "livemode": true,
      "created": 1790085931
    }
  ]
}

Retrieve a product’s perception

GET/v1/brands/{brand}/products/{product}/perception

How AI answers restitute the product’s identity sheet on a market over a period: verdict counts and score, then each differentiating attribute (USP) with the share of answers citing it and where to write it when it does not land. sheet_version is null for a product without an identity sheet — nothing is judged without one.

Parameters

  • brandstringrequired

    Brand id (br_…).

  • productstringrequired

    Product id (prod_…).

Returns

Returns the product_perception object. Raises an error if something goes wrong.

curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/products/prod_034fy4zIfaXW6rtqEz1nHT/perception \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
Response
{
  "object": "product_perception",
  "product": "prod_034fy4zIfaXW6rtqEz1nHT",
  "market": "FR",
  "period": "90d",
  "sheet_version": "string",
  "score": "string",
  "counts": "string",
  "by_model": "string",
  "attributes": "string",
  "livemode": true
}
Last updated on
MetricsQueries