Skip to main content

Manage variants and images

Add variants and images to an existing product, and look variants up by SKU — useful when syncing prices and stock from an external system.

When to use this​

Adding a size or color after a product exists, adjusting price or stock, swapping imagery, or matching your own SKUs to Shoplazza variants.

Prerequisites​

  • A working public app with OAuth and token storage — follow Develop app first. Every request below carries an Access-Token: {token} header, using the token you saved for each shop.
  • The product access scope granted during OAuth.
  • A product that already has options (create one with has_only_default_variant: false — see Create and update products).

Add a variant​

Add a variant to a product that already has options. price and position are required; option1 is the option value for the new variant.

POST /openapi/2026-01/products/{id}/variants

Request body:

{
  "variant": {
    "option1": "L",              // matches a value in the product's declared options
    "price": 19.9,
    "sku": "TS-L",
    "inventory_quantity": 100,
    "position": 3
  }
}

Response (excerpt, new variant under data.data.variant):

{
  "code": "Success",
  "data": {
    "variant": {
      "id": "d47c9f04-ae67-4480-a092-08945767ce4a",
      "product_id": "4d3e7859-455c-4899-a296-7befe731c585",
      "title": "L",
      "option1": "L",
      "position": 3,
      "price": 19.9,
      "sku": "TS-L",
      "inventory_quantity": 100,
      "created_at": "2026-07-02T02:58:01Z",
      "updated_at": "2026-07-02T02:58:01Z"
    }
  }
}

Full fields: see Create variant.

warning

You can only add a variant to a product that has options (has_only_default_variant: false). Calling this on a single-variant product fails with "At least a single variant is included in the product." Define the variants when you create the product, or restructure it first.

Update or delete a variant​

PUT /openapi/2026-01/variants/{id}

Request body:

{
  "variant": {
    "price": 24.9 // only the fields you want to change
  }
}

Returns the updated variant under data.data.variant. Full fields: see Update variant.

DELETE /openapi/2026-01/products/{id}/variants/{vid}

No request body. Deleting a variant returns no additional data. See Delete variant.

Look up variants by SKU​

When an external system keys on SKU, resolve it to a variant without knowing its id.

GET /openapi/2026-01/products/sku/{sku}/variants

Returns the list of variants matching that SKU, under data.data.variants. See List variants by SKU.

To update a variant directly by SKU, use PUT /variants/sku/{sku} — see Update variant by SKU.

Add an image​

Images belong to the product. Posting an image appends it to the gallery (it does not replace existing images). src is a public image URL.

POST /openapi/2026-01/products/{id}/images

Request body:

{
  "image": {
    "src": "https://cdn.example.com/tshirt-back.jpg" // publicly reachable image URL
  }
}

Response (excerpt, new image under data.data.image):

{
  "code": "Success",
  "data": {
    "image": {
      "id": "6c7d7bad-a4fe-48c3-95e5-51a36f20622f",
      "product_id": "4d3e7859-455c-4899-a296-7befe731c585",
      "position": 2,
      "src": "//cdn.example.com/tshirt-back.jpg",
      "created_at": "2026-07-02T02:58:13Z",
      "updated_at": "2026-07-02T02:58:13Z"
    }
  }
}

Full fields: see Create product image.

To reorder, change alt text, or remove an image, use PUT/DELETE /products/{id}/images/{image_id} — see Update product image and Delete product image.

List and count variants and images​

List a product's variants with GET /products/{id}/variants, or fetch one with GET /variants/{id}. Images work the same way with GET /products/{id}/images. Each also has a count endpoint.

See List variants, Get variant, Count variants, List product images, Get product image, and Count product images.

Next steps​