Object - Product

In order to fulfil orders, Jungle needs to know about your products. You can store your product information in Jungle, and manipulate it over time.

Creating a Product

Products are initially created with only a few properties that are used to identify it. Create one like this:

mutation ProductCreate {
  productCreate(
    input: { name: "My great product", xids: ["xid:jungle/Product:shopify/productid/my-shop:1237"], barcode: "123ABC" }
  ) {
    ok
    ... on MutationSuccess {
      objects {
        id
        typename
      }
    }
  }
}

The xids property in the example above references the product ID in an external system. Like most other Jungle objects, products can have multiple XIDs. Whenever a client refers to a product in the Jungle API, it can use an XID in place of the Jungle ID. More information on XIDs can be found here.

The response to this mutation will indicate that multiple objects were created: one for the product itself, and one for each of the XIDs. Jungle object IDs will be returned for all of them.

After creating a product, an API client can update it with additional information.

Updating a Product

Jungle's API provides a number of mutations for adding/changing your product details. Following are a few examples...

Set the Name and Description

Set a product's name and description like so:

mutation {
  productUpdate(
    input: {
      productId: "xid:jungle/Product:shopify/productid/my-shop:1234"
      name: "A better product name"
      description: "This product is great!"
    }
  ) {
    ok
  }
}

Set the Weight

Configure a product's weight (in grams) like so:

mutation {
  productUpdate(input: { productId: "xid:jungle/Product:shopify/productid/my-shop:1234", weight: 34.5 }) {
    ok
  }
}

Families, Variants and Options

A product that comes in several versions (a tee in sizes and colours, say) is modelled as a family with one variant per version. The family carries the shared name and description and defines the options the versions differ by; each variant carries its own SKU, barcode, pricing and inventory, and records which value it has chosen for every option of its family.

Create a family with its options, then create each variant into it. The option and value identifiers come back on the family's options:

mutation {
  productCreate(
    input: {
      type: { productTypeId: "xid:jungle/ProductType:jungle/product-type/family" }
      name: "Jungle Tee"
      options: [
        { name: "Size", values: [{ value: "S" }, { value: "M" }, { value: "L" }] }
        { name: "Colour", values: [{ value: "Black" }, { value: "Green" }] }
      ]
    }
  ) {
    ok
  }
}

mutation {
  productCreate(
    input: {
      family: { productId: "xid:jungle/Product:shopify/productid/my-shop:tee" }
      name: "Jungle Tee - M / Black"
      sku: "TEE-M-BLK"
      variantOptions: [{ optionId: "11", valueId: "102" }, { optionId: "12", valueId: "201" }]
    }
  ) {
    ok
  }
}

A variant must choose exactly one value for every option of its family, and no two variants of a family may share the same combination. To change a family's options later use productOptionsSet, which takes the complete set: options and values given with their id are updated in place (renaming keeps each variant's choice), those without an id are added, and anything not listed is removed. An option or value still used by a variant cannot be removed. A variant's choices are changed with productVariantOptionsSet, again as the complete selection.

To find the variant for a chosen combination, ask the family:

query {
  product(productId: "xid:jungle/Product:shopify/productid/my-shop:tee") {
    options {
      id
      name
      values {
        id
        value
      }
    }
    variant(input: { selections: [{ optionId: "11", valueId: "102" }, { optionId: "12", valueId: "201" }] }) {
      id
      sku
    }
  }
}

Limits: at most 10 options per family and 50 values per option. Names and values are unique within their scope, ignoring case.