Options and variants

Toolset product_options, 13 tools.

RecordsCopy Anchor Link

product_optionCopy Anchor Link

An option products are sold in, such as Size or Colour, with its values. An exclusive option belongs to one product; the others are shared and can be linked to many. get returns the values.

• Permission: products.read
• Tools: product_option_list, product_option_get

Filters on the list:

product_option_valueCopy Anchor Link

One value of a product option, such as Large. List the values of one option with option_id. get takes <option id>/<value id>.

• Permission: products.read
• Tools: product_option_value_list, product_option_value_get

Filters on the list:

product_variantCopy Anchor Link

A variant of any product: one purchasable combination of option values with its own SKU, price and stock settings. List across all products with q or sku; get takes <product id>/<variant id>.

• Permission: products.read
• Tools: product_variant_list, product_variant_get

Filters on the list:

ActionsCopy Anchor Link

product_option_createCopy Anchor Link

Create an option with its values.

Link it to products with product_options_link. is_exclusive makes it private to the one product it is linked to.

• Action key: product_option.create
• Permission: products.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "title": "Size",
  "values": [
    "S",
    "M",
    "L"
  ]
}

product_option_deleteCopy Anchor Link

Delete an option and its values.

• Action key: product_option.delete
• Permission: products.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: safe to repeat with the same input.

Example input:

{
  "option_id": "019bb39d-1471-7070-8cc5-bf1cb17d9bf9"
}

product_option_updateCopy Anchor Link

Rename an option or change its values.

values replaces the option values with this list: values left out are removed from the option and from the variants that use them, so read the option first.

• Action key: product_option.update
• Permission: products.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example input:

{
  "option_id": "019bb39d-1471-7070-8cc5-bf1cb17d9bf9",
  "title": "Shirt size"
}

product_option_value_deleteCopy Anchor Link

Delete one value of an option.

• Action key: product_option_value.delete
• Permission: products.write
• Approval: Always waits for a person to approve it.
• Effect: Changes the live store.
• Destructive: in compact mode it runs with run_destructive_action.
• Retries: safe to repeat with the same input.

Example input:

{
  "option_id": "019bb39d-1471-7070-8cc5-bf1cb17d9bf9",
  "value_id": "019bb3aa-7505-7a1f-84cc-94c44394c6ba"
}

product_option_value_updateCopy Anchor Link

Change the text of one option value.

• Action key: product_option_value.update
• Permission: products.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example input:

{
  "option_id": "019bb39d-1471-7070-8cc5-bf1cb17d9bf9",
  "value_id": "019bb3aa-7505-7a1f-84cc-94c44394c6ba",
  "value": "Extra large"
}

product_options_linkCopy Anchor Link

Add options to a product or take them off it, and add or remove values of its options.

add takes an existing option id, {option id, value_ids} to use some of its values, or a new option {title, values}. remove takes option ids to unlink. update adds or removes values of an option the product already has. The variants of the product are not changed: give a new option its values on each variant with product_variant_update.

• Action key: product_options.link
• Permission: products.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "product_id": "019bb58e-0ec1-79c1-9f40-d39d8d07674b",
  "add": [
    {
      "title": "Size",
      "values": [
        "S",
        "M"
      ]
    }
  ]
}

product_variant_images_updateCopy Anchor Link

Link images of the product to a variant, or unlink them.

Image ids come from product_get include gallery. The images stay on the product.

• Action key: product_variant_images.update
• Permission: products.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes the live store.
• Retries: safe to repeat with the same input.

Example input:

{
  "product_id": "019bb58e-0ec1-79c1-9f40-d39d8d07674b",
  "variant_id": "019bb7f3-10ac-7f8b-b47e-f5cd71dff2e1",
  "add": [
    "019bb316-8a7c-75c0-9993-d174937500ba"
  ]
}