Mutations / Products — Shopfront Developer Documentation

Mutation

addProductBackorder — Returns ProductBackorder

Arguments	Type	Description
product	ID!	The ID of the product to backorder
outlet	ID!	The ID of the outlet to backorder the product in
customer	ID!	The ID of the customer who wants the backorder
quantity	Float	The quantity of the product to order, defaults to 1
recurringPeriod	TimePeriod	The recurring period to reorder this product on, specify `null` if it's a one-off backorder
nextDueDate	DateTime	The next time this product is due to be ordered
notes	String	The notes relating to this backorder

Example Mutation

mutation AddProductBackorder($product: ID!, $outlet: ID!, $customer: ID!) {
    addProductBackorder(product: $product, outlet: $outlet, customer: $customer) {
        id,
        quantity,
        recurringPeriod,
        nextDueDate,
        notes
    }
}

# Example variables
{
    "product": "<PRODUCT>",
    "outlet": "<OUTLET>",
    "customer": "<CUSTOMER>"
}

Mutation

addProductCompetitionPrice — Returns Product

Scopes Required: edit_products

Arguments	Type	Description
product	ID!	The product to associate the competition price
competitor	String!	The name of the competitor
quantity	Float!	The quantity of the competitor's price
price	Float!	The competitor's price

Example Mutation

mutation AddProductCompetitionPrice($product: ID!, $competitor: String!, $quantity: Float!, $price: Float!) {
    addProductCompetitionPrice(product: $product, competitor: $competitor, quantity: $quantity, price: $price) {
        id,
        name,
        mdbId,
        type,
        active
    }
}

# Example variables
{
    "product": "<PRODUCT>",
    "competitor": "<COMPETITOR>",
    "quantity": "<QUANTITY>",
    "price": "<PRICE>"
}

Mutation

applyAllFutureCosts — Returns [FutureCost]

Scopes Required: edit_products

This mutation has been deprecated. The ApplyFutureCosts mutation should be used instead

Example Mutation

mutation ApplyAllFutureCosts {
    applyAllFutureCosts {
        id,
        cost,
        effectiveTime
    }
}

Mutation

applyAllFuturePrices — Returns [FuturePrice]

Scopes Required: edit_products

This mutation has been deprecated. The ApplyFuturePrices mutation should be used instead

Example Mutation

mutation ApplyAllFuturePrices {
    applyAllFuturePrices {
        id,
        quantity,
        price,
        priceEx,
        effectiveTime
    }
}

Mutation

applyFutureCost — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
id	ID!	The ID of the future cost to apply

Example Mutation

mutation ApplyFutureCost($id: ID!) {
    applyFutureCost(id: $id)
}

# Example variables
{
    "id": "<ID>"
}

Mutation

applyFutureCosts — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
ids	[ID!]	The list of future cost IDs to apply
applyAll	Boolean	Whether to apply all future costs. Cannot be used at the same time as ids

Example Mutation

mutation ApplyFutureCosts($ids: [ID!]) {
    applyFutureCosts(ids: $ids)
}

# Example variables
{
    "ids": [
        "<IDS>"
    ]
}

Mutation

applyFuturePrice — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
id	ID!	The ID of the future price to apply

Example Mutation

mutation ApplyFuturePrice($id: ID!) {
    applyFuturePrice(id: $id)
}

# Example variables
{
    "id": "<ID>"
}

Mutation

applyFuturePrices — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
ids	[ID!]	The list of future price IDs to apply
applyAll	Boolean	Whether to apply all future prices. Cannot be used at the same time as ids

Example Mutation

mutation ApplyFuturePrices($ids: [ID!]) {
    applyFuturePrices(ids: $ids)
}

# Example variables
{
    "ids": [
        "<IDS>"
    ]
}

Mutation

associateBarcode — Returns Product

Scopes Required: associate_barcode

Arguments	Type	Description
product	ID!	The ID of the product to associate the barcode to
barcode	String!	The barcode to associate
quantity	Float!	The quantity to associate the barcode to

Example Mutation

mutation AssociateBarcode($product: ID!, $barcode: String!, $quantity: Float!) {
    associateBarcode(product: $product, barcode: $barcode, quantity: $quantity) {
        id,
        name,
        mdbId,
        type,
        active
    }
}

# Example variables
{
    "product": "<PRODUCT>",
    "barcode": "<BARCODE>",
    "quantity": "<QUANTITY>"
}

Mutation

associateProduct — Returns Product

Scopes Required: create_products edit_products delete_products

Arguments	Type	Description
from	ID!	The original product
to	ID!	The product to associate the "from" to
supplier	ID	The supplier to move
supplierCode	String	The supplier code of the product, if provided, it will update the supplier code, not create a new one

Example Mutation

mutation AssociateProduct($from: ID!, $to: ID!) {
    associateProduct(from: $from, to: $to) {
        id,
        name,
        mdbId,
        type,
        active
    }
}

# Example variables
{
    "from": "<FROM>",
    "to": "<TO>"
}

Mutation

bulkDeleteProducts — Returns BulkDeleteProductsResponse

Scopes Required: delete_products

Arguments	Type	Description
ids	[ID!]!	The list of product IDs to delete

Example Mutation

mutation BulkDeleteProducts($ids: [ID!]!) {
    bulkDeleteProducts(ids: $ids) {
        deleted
    }
}

# Example variables
{
    "ids": [
        "<IDS>"
    ]
}

Mutation

bulkUpdateProducts — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
ids	[ID!]!	The IDs of the products to apply the status update to
status	ProductStatusEnum	The status to apply to the products
nameCase	ProductNameCaseEnum	What case to change the selected product's names

Example Mutation

mutation BulkUpdateProducts($ids: [ID!]!) {
    bulkUpdateProducts(ids: $ids)
}

# Example variables
{
    "ids": [
        "<IDS>"
    ]
}

Mutation

createFutureCosts — Returns [FutureCost]

Scopes Required: edit_products

Arguments	Type	Description
futureCosts	[FutureCostInput!]!	The future costs to add

Example Mutation

mutation CreateFutureCosts($futureCosts: [FutureCostInput!]!) {
    createFutureCosts(futureCosts: $futureCosts) {
        id,
        cost,
        effectiveTime
    }
}

# Example variables
{
    "futureCosts": [
        {
            "item": "<ITEM>",
            "type": "PRODUCT",
            "cost": "<COST>",
            "effective": "<EFFECTIVE>"
        }
    ]
}

Mutation

createFuturePrices — Returns [FuturePrice]

Scopes Required: edit_products

Arguments	Type	Description
futurePrices	[FuturePriceInput]	The future prices to add

Example Mutation

mutation CreateFuturePrices($futurePrices: [FuturePriceInput]) {
    createFuturePrices(futurePrices: $futurePrices) {
        id,
        quantity,
        price,
        priceEx,
        effectiveTime
    }
}

# Example variables
{
    "futurePrices": [
        {
            "item": "<ITEM>",
            "type": "PRODUCT",
            "quantity": "<QUANTITY>",
            "effective": "<EFFECTIVE>"
        }
    ]
}

Mutation

createProduct — Returns Product

Scopes Required: create_products

Arguments	Type	Description	Validation
name	String	The name of the product
type	ProductTypeEnum!	The type of product this is
status	ProductStatusEnum	The status of the product
caseQuantity	Float	The case quantity of the product. It is no longer valid to supplier this as a decimal value	Minimum: 1 Maximum: 9,999
requestQuantity	Boolean	Whether the product should ask for the quantity rather than starting at the base quantity (does not affect barcodes)
requestPrice	Boolean	Whether the product should ask for its price rather than having preset pricing
description	String	An HTML description of the product
category	ID	The product\'s category
brand	ID	The product\'s brand
family	ID	A family is for grouping of similar products but separate varieties that allow prices to mix and match together
alignFamily	Boolean	Align the all the products in the family to the prices of this product
tags	[ID]	The tags to assign this product
suppliers	[ProductSupplierInput]	The suppliers this product can be purchased from
coreSupplier	ID	The core / main supplier this product is purchased from (must appear in the `suppliers` array)
orderNotes	String	Notes to display when ordering a product
invoiceNotes	String	Notes to display when receiving this product on an order
taxRate	ID	The tax rate this product is sold with, defaults to the Vendor's default tax rate
costTaxRate	CostTaxRateID	The tax rate used when handling this product\'s costs, defaults to the product's tax rate
useScales	Boolean	Whether this product can be weighed using scales
useBarcodeTemplates	Boolean	Whether this product can have barcodes with barcode templates
usePriceLabel	Boolean	`usePriceLabels` has been superseded by `useBarcodeTemplates`
preventManualDiscounts	Boolean	Whether this product can have a manual discount applied
ignorePriceHostChanges	Boolean	Whether this product can receive price changes from a host file.
ignoreBarcodeHostChanges	Boolean	Whether this product can receive barcode changes from a host file.
cost	Float	The cost for this product
costPercentage	Boolean	Whether the cost is a percentage of the sell price
trackInventory	Boolean	Whether to track inventory for this product
ticketInformation	[AdditionalValueInput]	The ticketing information for this product
image	String	The main image for this product
alternateImages	[String]	The alternative images for this product
prices	[ProductPriceInput]	The prices for this product
barcodes	[ProductBarcodeInput]	The barcodes for this product
inventory	[ProductInventoryInput]	The inventory for this product
loyalty	[ProductLoyaltyInput]	The loyalty for this product to be earned and redeemed
contains	[ProductContainsInput]	The item that are contained in this product (used only for "PACKAGE" and "BASKET" types
metcashMSC	String	The Metcash classification for the product

Example Mutation

mutation CreateProduct($type: ProductTypeEnum!) {
    createProduct(type: $type) {
        id,
        name,
        mdbId,
        type,
        active
    }
}

# Example variables
{
    "type": "NORMAL"
}

Mutation

deleteBarcodes — Returns boolean

Scopes Required: edit_barcodes

Arguments	Type	Description
barcodes	[BarcodeDeleteInput!]!	The list of barcodes to delete

Example Mutation

mutation DeleteBarcodes($barcodes: [BarcodeDeleteInput!]!) {
    deleteBarcodes(barcodes: $barcodes)
}

# Example variables
{
    "barcodes": [
        {
            "product": "<PRODUCT>",
            "code": "<CODE>"
        }
    ]
}

Mutation

removeFutureCost — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
id	ID!	The ID of the future cost to delete

Example Mutation

mutation DeleteFutureCost($id: ID!) {
    removeFutureCost(id: $id)
}

# Example variables
{
    "id": "<ID>"
}

Mutation

removeFutureCosts — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
ids	[ID!]	The list of future cost IDs to apply
removeAll	Boolean	Whether to remove all future prices. Cannot be used at the same time as ids

Example Mutation

mutation DeleteFutureCosts($ids: [ID!]) {
    removeFutureCosts(ids: $ids)
}

# Example variables
{
    "ids": [
        "<IDS>"
    ]
}

Mutation

removeFuturePrice — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
id	ID!	The ID of the future price to delete

Example Mutation

mutation DeleteFuturePrice($id: ID!) {
    removeFuturePrice(id: $id)
}

# Example variables
{
    "id": "<ID>"
}

Mutation

removeFuturePrices — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
ids	[ID!]	The list of future price IDs to apply
removeAll	Boolean	Whether to remove all future prices. Cannot be used at the same time as ids

Example Mutation

mutation DeleteFuturePrices($ids: [ID!]) {
    removeFuturePrices(ids: $ids)
}

# Example variables
{
    "ids": [
        "<IDS>"
    ]
}

Mutation

deleteProduct — Returns Product

Scopes Required: delete_products

Arguments	Type	Description
id	ID!	The ID of the product to delete

Example Mutation

mutation DeleteProduct($id: ID!) {
    deleteProduct(id: $id) {
        id,
        name,
        mdbId,
        type,
        active
    }
}

# Example variables
{
    "id": "<ID>"
}

Mutation

deleteProductBackorder — Returns boolean

Scopes Required: update_product_backorder

Arguments	Type	Description
id	ID!	The ID of the backorder to remove

Example Mutation

mutation DeleteProductBackorder($id: ID!) {
    deleteProductBackorder(id: $id)
}

# Example variables
{
    "id": "<ID>"
}

Mutation

mergeProducts — Returns Product

Scopes Required: create_products delete_products

Arguments	Type	Description
name	String	The name of the product
type	ProductTypeEnum!	The type of product this is
status	ProductStatusEnum	The status of the product
caseQuantity	Float	The case quantity of the product
requestQuantity	Boolean	Whether the product should ask for the quantity rather than starting at the base quantity (does not affect barcodes)
requestPrice	Boolean	Whether the product should ask for its price rather than having preset pricing
preventManualDiscounts	Boolean	Whether this product can have a manual discount applied
ignorePriceHostChanges	Boolean	Whether this product can receive price changes from a host file.
ignoreBarcodeHostChanges	Boolean	Whether this product can receive barcode changes from a host file.
description	String	An HTML description of the product
category	ID	The product's category
brand	ID	The product's brand
family	ID	A family is for grouping of similar products but separate varieties that allow prices to mix and match together
tags	[ID]	The tags to assign this product
suppliers	[ProductSupplierInput]	The suppliers this product can be purchased from
orderNotes	String	Notes to display when ordering a product
taxRate	ID	The tax rate this product is sold with, defaults to the Vendor's default tax rate
useScales	Boolean	Whether this product can be weighed using scales
useBarcodeTemplates	Boolean	Whether this product can have barcodes with barcode templates
usePriceLabel	Boolean	usePriceLabels has been superseded by useBarcodeTemplates
cost	Float	The cost for this product
costPercentage	Boolean	Whether the cost is a percentage of the sell price
costs	[ProductCostInput]	All of the costs this product has (cannot be used with the `cost` field)
trackInventory	Boolean	Whether to track inventory for this product
ticketInformation	[AdditionalValueInput]	The ticketing information for this product
image	String	The main image for this product
alternateImages	[String]	The alternative images for this product
prices	[ProductPriceInput]	The prices for this product
barcodes	[ProductBarcodeInput]	The barcodes for this product
inventory	[ProductInventoryInput]	The inventory for this product
loyalty	[ProductLoyaltyInput]	The loyalty for this product to be earned and redeemed
contains	[ProductContainsInput]	The item that are contained in this product (used only for "PACKAGE" and "BASKET" types
merge	[ID]	The list of product IDs to merge into the new product

Example Mutation

mutation MergeProducts($type: ProductTypeEnum!) {
    mergeProducts(type: $type) {
        id,
        name,
        mdbId,
        type,
        active
    }
}

# Example variables
{
    "type": "NORMAL"
}

Mutation

removeProductCompetitionPrice — Returns boolean

Scopes Required: edit_products

Arguments	Type	Description
product	ID!	The ID of the product to remove the competition price from
competitor	String!	The name of the competitor whose price should be removed
quantity	Float!	The quantity of the competition price to remove

Example Mutation

mutation RemoveProductCompetitionPrice($product: ID!, $competitor: String!, $quantity: Float!) {
    removeProductCompetitionPrice(product: $product, competitor: $competitor, quantity: $quantity)
}

# Example variables
{
    "product": "<PRODUCT>",
    "competitor": "<COMPETITOR>",
    "quantity": "<QUANTITY>"
}

Mutation

updateProduct — Returns Product

Scopes Required: edit_products

Arguments	Type	Description	Validation
id	ID!	The ID of the product you want to update
name	String	The name of the product
status	ProductStatusEnum	The status of the product
caseQuantity	Float	The case quantity of the product	Minimum: 0 Maximum: 10,000
requestQuantity	Boolean	Whether the product should ask for the quantity rather than starting at the base quantity (does not affect barcodes)
requestPrice	Boolean	Whether the product should ask for its price rather than having preset pricing
description	String	An HTML description of the product
category	ID	The product's category
brand	ID	The product's brand
family	ID	A family is for grouping of similar products but separate varieties that allow prices to mix and match together
alignFamily	Boolean	Align the all the products in the family to the prices of this product
tags	[ID]	The tags to assign this product
suppliers	[ProductSupplierInput]	The suppliers this product can be purchased from
coreSupplier	ID	The core / main supplier this product is purchased from (must appear in the `suppliers` array)
orderNotes	String	Notes to display when ordering a product
invoiceNotes	String	Notes to display when receiving this product on an order
taxRate	ID	The tax rate this product is sold with
costTaxRate	CostTaxRateID	The tax rate used when handling this product's costs
cost	Float	The cost for this product(cannot be used with the `costs` array)
costs	[ProductCostInput]	All of the costs this product has(cannot be used with the `cost` field)
costPercentage	Boolean	Whether this product's cost is a percentage of its sell price (cannot be used with the `costs` array)
trackInventory	Boolean	Whether inventory should be tracked for this product
useScales	Boolean	Whether this product can be weighed using scales
useBarcodeTemplates	Boolean	Whether this product can have barcodes with barcode templates
usePriceLabel	Boolean	usePriceLabels has been superseded by useBarcodeTemplates
preventManualDiscounts	Boolean	Whether this product can have a manual discount applied
ignorePriceHostChanges	Boolean	Whether this product can receive price changes from a host file.
ignoreBarcodeHostChanges	Boolean	Whether this product can receive barcode changes from a host file.
ticketInformation	[AdditionalValueInput]	The ticketing information for this product (If set, this will override the old values)
image	String	The main image for this product
alternateImages	[String]	The alternative images for this product
prices	[ProductPriceInput]	The prices for this product
barcodes	[ProductBarcodeInput]	The barcodes for this product
inventory	[ProductInventoryInput]	The inventory for this product
loyalty	[ProductLoyaltyInput]	The loyalty for this product to be earned and redeemed
contains	[ProductContainsInput]	The item that are contained in this product (used only for "PACKAGE" and "BASKET" types)
metcashMSC	String	The Metcash classification for this product

Example Mutation

mutation UpdateProduct($id: ID!) {
    updateProduct(id: $id) {
        id,
        name,
        mdbId,
        type,
        active
    }
}

# Example variables
{
    "id": "<ID>"
}

Mutation

updateProductBackorder — Returns ProductBackorder

Scopes Required: update_product_backorder

Arguments	Type	Description
id	ID!	The ID of the backorder to update
quantity	Float	The quantity of the backorder
recurringPeriod	TimePeriod	The recurring period to reorder this product on
nextDueDate	DateTime	The next time this product is due to be ordered
notes	String	The notes relating to this backorder

Example Mutation

mutation UpdateProductBackorder($id: ID!) {
    updateProductBackorder(id: $id) {
        id,
        quantity,
        recurringPeriod,
        nextDueDate,
        notes
    }
}

# Example variables
{
    "id": "<ID>"
}

Mutation

updateProducts — Returns [Product]

Scopes Required: edit_products

This method is currently unstable, we would highly recommend using the single updateProduct mutation as it has significantly better error handling and more features.

Returns every product actually affected by the update, not just the ones provided - a family price change also returns the family's other products.

Arguments	Type	Description
products	[ProductInput]!	The products to update

Example Mutation

mutation UpdateProducts($products: [ProductInput]!) {
    updateProducts(products: $products) {
        id,
        name,
        mdbId,
        type,
        active
    }
}

# Example variables
{
    "products": [
        {
            "id": "<ID>",
            "quantity": "<QUANTITY>",
            "price": "<PRICE>",
            "alignFamily": "<ALIGN_FAMILY>"
        }
    ]
}