Products¶
The Products push creates products in Shopify and updates them, with their options, variants and metafields. It also updates existing variants by their Variant Id, for a price or SKU change without touching the rest of the product.
On a push connector, select Products as the Shopify Import Type. The push sends each product through Shopify's productSet mutation, and its variants through productVariantsBulkUpdate when it updates them by Variant Id.
Every Shopify product has at least one variant. The variant holds the price, SKU and inventory settings. A product without size or colour options has exactly one variant, its main variant.
Records¶
| Record | Under | One for each |
|---|---|---|
| Product | product | |
| Variants | Product | variant of the product |
| Product Metafields | Product | metafield on the product |
| Variant Metafields | Variants | metafield on the variant |
Creating and Updating¶
Product Id decides between creating a product and updating one. Leave it blank to create the product, and IMan writes the new id back. Map the product's id to update it. The id can be numeric or a gid, such as gid://shopify/Product/1234567890. See Update Strategy.
A Product with One Variant¶
Map the Main Variant fields on the Product record, such as Main Variant SKU and Main Variant Price, and leave out Variants records. To update the main variant, map Main Variant Variant Id as well as Product Id.
A product can have Main Variant fields or Variants records, not both. A product with both fails:
The Main Variant fields can't be used on a product that has Variant rows; send the main variant as a Variant row instead.
A Product with Options and Variants¶
Name the product's options with Option 1 Name to Option 3 Name on the Product record, such as Colour and Size. Give each Variants record its values in Option 1 Value to Option 3 Value, such as Red and Large. IMan builds the product's option list from the values its variants use.
How the push treats the variants depends on whether the Variants records carry a Variant Id:
- No Variants record has a Variant Id. The push sets the product's variants to the ones the records list. Shopify creates those it does not have, matching on the option values, and deletes any variant the records leave out. Send every variant the product should keep.
- Every Variants record has a Variant Id. The push updates those variants and nothing else. It leaves the product's other variants and its options as they are. The product's own fields go first, when the record sets any. Product Id is required.
- Some records have a Variant Id and some do not. The product fails, and IMan sends nothing for it:
Either every variant of the product needs a Variant Id, to update those variants, or none of them, to set the product's variants; 2 of 3 have one.
To change only prices or SKUs, read the variants with the Product Variants pull, set the new values in a Map transform, and push them with their Variant Ids and Product Id.
Available Quantity (New Variant Only) and Inventory Location (New Variant Only) set a new variant's opening stock at one location. Shopify ignores them on an existing variant. Use Inventory Levels v2 to set stock afterwards.
Key Fields¶
| Field | Record | Effect |
|---|---|---|
| Product Id | Product | Blank creates the product. A Shopify product id updates it. Written back after a create |
| Handle | Product | The product's URL handle. Shopify makes one from the title when it is blank |
| Status | Product | ACTIVE, DRAFT or ARCHIVED, in capitals |
| Inventory Management (Is Tracked) | Variants, and Main Variant on Product | True tracks the variant's stock. shopify, the REST value, also means tracked. Anything else means not tracked |
| Option 1 Name to Option 3 Name | Product | The product's option names |
| Main Variant Variant Id | Product | The main variant to update. Written back after a create |
| Variant Id | Variants | Updates that variant through productVariantsBulkUpdate. Written back for a new variant |
| Option 1 Value to Option 3 Value | Variants | The variant's option values |
| Inventory Item ID | Variants | Written back. Use it with Inventory Levels v2 |
| Synchronous Update | Product | Blank or True waits for Shopify to finish the product. False lets Shopify finish it in the background, and IMan gets no ids back |
| Use Bulk Operations | Product | True sends the run through bulk operations |
The other fields carry the product's and variants' data: title, description, vendor, product type, tags, SEO title, gift card, barcode, prices, cost, weight, tax, shipping and unit pricing.
Metafields¶
A product and each of its variants can carry metafields in two ways. Use whichever suits the source data:
- Metafield slots. Metafield 1 to Metafield 10 on the Product record belong to the product. Main Variant Metafield 1 to 10 belong to its main variant. Metafield 1 to 10 on a Variants record belong to that variant. Each slot has a Namespace, Key, Type and Value.
- Metafields records. A Product Metafields record under the product, or a Variant Metafields record under a variant, holds one metafield each. Use them when the number of metafields varies.
The rules match the Metafields push:
- A slot with no Key is unused. A Metafields record needs a Key.
- A blank Namespace is
custom. - A blank Type uses the metafield's definition.
- A blank Value deletes the metafield. The Value field must therefore be on the transform.
IMan writes the product first, then sends its metafields to the ids Shopify returned. A metafield that Shopify refuses fails its record, and the message says IMan wrote the product itself:
The product was written, but metafield custom.season on gid://shopify/Product/1234567890 failed: ...
The push never sends metafields inside productSet. That would delete every metafield on the product it was not sent, including other apps'. Setting one metafield twice on the same owner fails the record before IMan writes it.
Speed and Bulk Operations¶
The push sends one product at a time. MaxConcurrentRequests in the connection string lets it send several metafield requests at once. Designer runs send one at a time.
With Use Bulk Operations on, IMan sends the run through Shopify bulk operations. Records that change the same Product Id go in successive rounds. Each round sends the products, then the variant updates, then the metafields. When Shopify writes a product's own fields but refuses its variants, the product logs:
Errors¶
Action on Transform Error applies as usual. A product Shopify refuses fails with Shopify's message, and the run goes on or stops as the setting says. A product that fails one of the checks above fails before IMan sends anything for it.
Access Scopes¶
The push needs write_products, and write_inventory for a new variant's opening stock. See Access Scopes.
Shopify Reference¶
productSet and productVariantsBulkUpdate in Shopify's GraphQL Admin API reference.