Skip to main content

Build child products

POST 
/pcm/products/:productID/build

With product variations in Product Experience Manager, you can create product variations and different options for each variation and use both to create child products for a product. Each child product is a unique combination of options associated with the product.

Child products inherit attributes from their parent products. When you make changes to the attributes of the parent products, you can rebuild your child products, ensuring that changes to the parent products are propagated to the child products.

Alternatively, you can modify a child product independently, without impacting its parent product. For example, you may prefer the status of your child product to be live, while keeping the parent product's status as draft. When you directly update a child product, it becomes independent of its parent product. In other words, any subsequent changes made to the parent product are not automatically reflected in the child product when you rebuild the parent product and its child products. Once a child product is independent of its parent, you cannot recreate the association between the child product and its parent. You must delete the child product and rebuild the parent to recreate the child product.

Following on from that, if you add the same flow to both a parent and child product, the child flow values are not affected by changes to the parent flow values in a rebuild.

Using Build Rules​

When building your child products, you can build all products related to a product.

Alternatively, you can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. You can do this using build_rules. build_rules are combinations of variation option IDs that you wish to include or exclude when building your child products.

note

You do not need to configure any build_rules in the following scenarios:

  • Child products must be built with all variation options. Simply, use the Create a product or Update a product endpoints with no build_rules specified.
  • Child products must be built apart from all options for a specific variation. In this case, you must remove the variation and use the Create a product or Update a product endpoints with no build_rules specified. In other words, using our example, if none of the size options should be included, then remove the size variation.

The build_rules contain:

  • (Required) default: specifies the default behavior.
  • (Optional) include: specifies the option IDs to include when the child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations. See Invalid Build Rules.
  • (Optional) exclude: specifies the option IDs to exclude when the child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations. See Invalid build rules.

When building child products, Commerce compares each combination of option IDs to these rules to determine how your child products should be built, depending on how you have configured the build_rules. It depends on your requirements how you configure your build_rules.

Invalid Build Rules​

The build_rules are invalid if both the option IDs come from the same variation. Combinations of option IDs in the nested arrays must come from different variations.

If Commerce cannot resolve the build_rules a could not determine whether to include or exclude a child product due to ambiguous rules error is returned. This error can occur, for example, if you have the same number of variation option IDs in both the include and exclude arrays and the variation option IDs match.

Building Child Products​

Building child products is an asynchronous operation. When you build child products, a job is created. The jobId of the job is displayed in the response. When the job is complete, the build child products operation is also complete. You can use the jobId to see the status of your job using the Get a Job endpoint.

Jobs are processed one at a time. You can continue to send build child product requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See Jobs.

Re-building child products after adding or removing a new variation changes the total number of child products that you can generate from a parent product. When you rebuild the child products after updating variations associated with the parent product, all existing child products that belong to a parent product are deleted. New child products are created with new product IDs.

If you have any bundles that reference child products directly, then you must update the bundles with the new child product IDs.

However, re-building child products after adding or removing an option does not change the existing product IDs.

Request​

Path Parameters

    productID stringrequired

    A unique identifier for the product.

Body

    object

Responses​

Successfully started building child products

Schema
    data objectrequired
    id stringrequired

    A unique identifier generated when a job is created.

    type stringrequired

    Possible values: [pim-job]

    This represents the type of resource object being returned. Always pim-job.

    attributes objectrequired
    started_at date-timenullablerequired

    The date and time a job is started.

    completed_at date-timenullablerequired

    The date and time a job is completed.

    created_at date-timerequired

    The date and time a job is created.

    updated_at date-timerequired

    The date and time a job is updated.

    type stringrequired

    Possible values: [child-products, product-import, product-export, hierarchy-duplicate, price-import]

    The status of a job.

    • pending - Commerce has received the request but is currently busy processing other requests.
    • started - Commerce has started processing the job.
    • success - The job has successfully completed.
    • failed - The job has failed.
    status stringrequired

    Possible values: [pending, cancelled, started, success, failed]

    meta objectrequired
    x_request_id stringrequired

    Applies to all job types. A unique request ID is generated when a job is created.

    copied_from string

    Applies to hierarchy-duplicate job types. The ID of the original hierarchy that you duplicated.

    hierarchy_id string

    Applies to hierarchy-duplicate job types. The duplicated hierarchy ID.

    file_locations string[]nullable

    If the job type is product_export, a link to the file is created when running a job.

    filter string

    The entities included in the job. For example, if the job type is product-export, the PXM products included in the export.

Loading...