Getting started with Constructor recommendations

What you'll achieve

Connect your Constructor account to Order Editing, choose the recommendation pods you want to use, and add Constructor Recommendations to an upsell strategy. Customers can then see products selected by Constructor.

Before you begin

You need:

• An active Constructor account with a Shopify product catalog.
• Your Constructor index key, also called the API key. This identifies the catalog index you want to use.
• At least one recommendation pod in Constructor.

Your Constructor management API token is a separate, optional credential. A token with permission to read recommendation pods for this index lets Order Editing load your pod list. Without it, you can paste pod IDs manually.

Connect Constructor

1. Open the Shopify admin and go to Apps > Order Editing.
2. Select Integrations, then select Constructor.
3. Enter the index key for your intended catalog in Constructor index key. Do not enter the API token in this field.
4. Select Check status to verify and save a new index connection.
5. Optional: enter your token in Constructor management API token (optional), then select Save token and load pods. This saves only the token and refreshes the pod list.

When the connection succeeds, Order Editing shows Connection verified and saves a new connection so you can choose pods.

Choose and verify recommendation pods

1. Go to Recommendation pods on the Constructor integration page.
2. Select a discovered pod, or enter a pod ID and press Enter. Use the pod ID to distinguish pods with the same name.
3. Wait for Order Editing to verify the pod.
4. Repeat for each pod you want to use.
5. Select Save Constructor settings.

A context-free pod must return products before you can save it. Pods based on products in an order can show Fills in with real orders because they need order context to return recommendations.

Add Constructor to an upsell strategy

1. Select Upsell Strategies in Order Editing.
2. Create a strategy or open an existing strategy.
3. Choose a supported placement: Thank You, Order Status, or Customer Accounts.
4. Add the Constructor Recommendations module.
5. Choose a Recommendation pod.
6. If the pod uses query recommendations, enter a Search phrase.
7. Optional: open Advanced settings and set Maximum Products. The default is 10, and the allowed range is 1 to 20.
8. Configure the offer content, then select Save.
9. Save and activate the upsell strategy.

Preview the offer

Use the strategy preview to review the products and offer content before activating the strategy.

If your selected pod uses products from the order as context, its setup preview may be empty. Open an existing eligible order to check the customer journey with real order context. You do not need to create a new order to confirm the setup.

Understand Constructor reporting

Order Editing sends a recommendation view when Constructor products are served. It reports an accepted product after the order edit commits and, when payment is due, after the order is paid. If a customer removes the accepted product before payment, Order Editing does not report that product as purchased.

Purchase reporting requires your Constructor catalog to use numeric Shopify product and variant IDs. Catalogs using product handles or Shopify GIDs can provide recommendations, but matching accepted sales back to those catalog items is not currently supported.

Troubleshoot the connection

The index key is not accepted

Confirm that you copied the index key for the intended catalog from Integration in Constructor, enter it again, and select Check status. The index key is also called the API key; it is different from the optional API token.

The API token is not accepted

Check the Pod discovery message. A connected index does not prove that a management token can list pods. Verify that the token can read recommendation pods for the same index. You can continue by entering pod IDs manually while discovery is unavailable. An empty list is shown separately from an unavailable response.

Remove a saved management token

Select Remove saved token and confirm. This removes only the management token; your index key, saved pods and integration status stay unchanged. Pod verification failures do not block removal. Leaving the token field blank keeps the saved token. To replace it, enter a new token and select Save token and load pods. If saving or removal fails, the page shows an error and you can retry.

A pod returns no products

Confirm that the pod is active in Constructor and that its product identifiers are numeric Shopify product IDs, Shopify product GIDs, or exact Shopify product handles. Custom SKU identifiers that do not match Shopify handles are not supported. For a query recommendation pod, also confirm that Search phrase is filled in.

Products must also meet your store's market, visibility and availability rules before they can appear in an offer.

If the pod shows Fills in with real orders, use an existing eligible order to provide the product context it needs.

A pod cannot be verified

Try the verification again. If it remains unavailable, check the pod in Constructor before saving it in Order Editing.

Outcome

Your active upsell strategy can now show Constructor recommendations on supported post-purchase placements.

What's next

Monitor the strategy in Analytics. If your catalog uses numeric Shopify product and variant IDs, compare accepted products with the corresponding pod reporting in Constructor after eligible edits are committed and paid when payment is required.