Skip to content
YoPrintDevelopers

Rename sizes and colors of a product

Open .md

POST/v1/api/store/{team_slug}/product/{hash_id}/variant/rename_options

v1Operation ID v1_public_product_variant_rename_options

Each size or color keeps its id and takes the new label, and a color may take a new hex, on every variant of the product, deleted copies included. A color sent with only a hex keeps its current name. Orders, quotes and invoices show the new name; purchase order lines keep the name they were created with. A label another size, or another color, of the product already has returns 422 option_label_taken; an option the product does not use returns 422 option_unknown. Returns the product's live variants.

Permission

Needs the Manage Products permission at the level that can update products.

Path parameters

  • team_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team
  • hash_idstringrequired

    The product's id (id from List products). A hash id from an earlier answer; unique keys and document numbers (such as PO0042) don't work here.

    • Example EDhVUaC6jbLbed

Request body

application/json, required.

  • optionsarray of objectsrequired
    • 1 to 100 items
    Fields of each item (4)
    • idstringrequired

      The size or color id, as in size_data or color_data.

      • At most 191 characters
    • typestringrequired
      • One of: "size", "color"
    • hexstring | null

      Colors: the new hex color, # and 6 or 3 hex digits, such as #1F2937.

    • labelstring | null

      The new name. Required for sizes, and for colors sent without hex.

      • At most 191 characters

Response

200Successful response.

  • dataarray of objectsrequired

    Every live variant of the product, in id order.

    Fields of each item (23)
    • typestringrequired
      • Always "variant_option"
    • default_priceinteger | number | stringrequired

      This variant's selling price. Never null. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.

    • idstringrequired

      The variant id: the db_variant line's product id.

    • phased_outbooleanrequired
    • trashedbooleanrequired
    • barcodestring | null
    • brandstring | null

      The parent product's brand.

    • color_hexstring | null
    • color_idstring | null
    • color_labelstring | null
    • descriptionstring | null

      The parent product's description.

    • enableboolean
    • phased_out_atstring (date-time) | null
    • phased_out_byobject | null

      Who did it, as {id, name}; null when on sale or nobody was recorded.

      Child fields (2)
    • price_dataobject | array

      Prices for pricing groups, as saved: keyed by the pricing group's internal number (not its hash id), each {"price": <thousandths>}. An empty list [] when there are none.

    • size_idstring | null
    • size_labelstring | null
    • supplier_idstring | null
    • taxableboolean

      The parent product's taxable.

    • titlestring | null

      The parent product's title.

    • track_inventoryboolean
    • vendor_idstring

      The vendor id, or an empty string when none.

    • weightnumber | string | null
  • statusintegerrequired
  • successbooleanrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

    When
    Your role cannot update products. This 403 has a short body, {"message": "Insufficient Permission"}, with no success or error.
    Fix
    Ask a team owner to set Manage Products to "Users CAN view, update and create products".

  • 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

    When
    No live variant product with this id. error.code is null and error.message names the record type.
    Fix
    Check the product id.

  • 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

    When
    The new name is taken by another option of the product (error.code option_label_taken), or the option is not on the product (option_unknown).
    Fix
    Pick another name; reload the product's options.
    When
    options is empty or has more than 100 items, an item is missing type, id or a label, or a hex is not a hex color. error.code is validation_failed.
    Fix
    Fix each field named in error.fields; its keys are field paths such as contact.0.phone.

Notes

  • Pricing rules match a line's saved size name. Renaming a size can change which product rules apply to new lines.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com