Catalog configuration

The catalog configuration tells Mirakl Connect how the channel handles offers and products.

Configuring a channel's catalog behavior is a required step. Until the connector configures it, Mirakl Connect does not know which offer flows the channel accepts, and no offer reaches the channel.

Four parts make up the configuration, and they all go in the same request:

• Offer attributes: the channel offer attributes that do not exist in Mirakl Connect. They go in the custom_attributes array of the offer_configuration node.

• Offer use cases: the offer flows the channel supports, and the offer fields each flow needs. They go in the use_case_configurations node.
• The price and stock lifecycle: the granularity the prices and the stock reach your connector at, either once for the store or once for each sub-channel. It goes in the standard_prices, discount_prices, and stock_quantities nodes.
• Product grouping: the attribute Mirakl Connect groups related products on, if the channel needs them in one submission. It goes in the behaviors node.

The connector sends the configurations with the configureChannelCatalog API. This API works in replace mode: each call sends the complete configuration and overwrites the previous one. For more information, refer to the REST APIs reference.

An offer attribute is a channel-specific value attached to an offer. As an example, the condition of the product, with values such as new or refurbished, is a typical offer attribute.

Declare each attribute in the custom_attributes array of the offer_configuration node. Give each one an id, because the offer use cases reference the attribute by that id.

Give each one a requirement_level, with one of three values:

• REQUIRED: the channel rejects an offer without this attribute. The seller must fill it before the offers can go live.
• RECOMMENDED: the channel accepts an offer without this attribute, but uses it when it is present.
• OPTIONAL: the channel accepts an offer without this attribute.

Declare every offer attribute the channel accepts, not only the required ones. The seller can fill only the attributes you declare.

An offer use case is one offer flow between Mirakl Connect and the channel. There are two, and use_case_configurations must hold both:

• offer_creation: the flow that creates an offer on the channel.
• offer_update: the flow that updates the definition of an existing offer.

Declare at least one use case as SUPPORTED. With both set to UNSUPPORTED, Mirakl Connect sends no OfferUpsertEvent, and no offer is created or updated on the channel.

Declare DISCOUNT_PRICE in a supported use case, in required or in optional. Without it, the seller cannot enable the discount price synchronization, and the field always arrives as IGNORE.

The PriceStockUpsertEvent is not gated by this configuration. You cannot disable it, and it flows for any offer that exists on the channel.

To see how these events drive the synchronization, read Catalog flow.

Each use case holds three nodes:

• support: either SUPPORTED or UNSUPPORTED. UNSUPPORTED means Mirakl Connect never sends the matching OfferUpsertEvent.
• required: the fields the channel cannot accept an offer without. Mirakl Connect sends an offer only when it carries all of them.
• optional: the fields the channel accepts but does not need.

Send support and required in both use cases, even when a use case is UNSUPPORTED.

The required and optional nodes hold the same two attribute lists:

• standard_attributes: fields that already exist in the offer data model. This is a closed set of five values, listed below, and the API rejects anything else.
• custom_attributes: the channel attributes, referenced by the id you gave them in Offer attributes. This set is free-form, because the ids are your own.

The two nodes for required and optional attributes, change the OfferUpsertEvent in a different way for each use case.

On offer_creation:

• required selects the offers. Mirakl Connect sends the event only for an offer that has a value for every field in required. An offer that misses one gets no event, and its offer status does not change.
• optional does not select the fields. The event carries every field that Mirakl Connect holds for the offer, whatever the two lists hold.

On offer_update:

• required selects the offers, as on creation.
• required and optional together select the fields. The event carries product_id, and only the fields that one of the two lists holds.
• A field that neither list holds does not reach your connector.

An offer attribute can appear in two places, and each place has a different effect:

• The requirement_level of the attribute, in Offer attributes, sets what the seller must fill in Mirakl Connect.
• The required and optional lists of a use case set which offers Mirakl Connect sends, and which fields an update carries.

In the configuration below:

• Offer creation requires the SKU, the standard price, the stock, and the condition attribute.
• Offer creation also accepts the product identifiers, a discount price, and the warranty attribute, but does not need them.
• Offer update requires the same three standard fields, and no offer attribute.

{
  "use_case_configurations": {
    "offer_creation": {
      "support": "SUPPORTED",
      "required": {
        "standard_attributes": ["ID", "STANDARD_PRICE", "STOCK"],
        "custom_attributes": ["condition"]
      },
      "optional": {
        "standard_attributes": ["GTIN", "DISCOUNT_PRICE"],
        "custom_attributes": ["warranty"]
      }
    },
    "offer_update": {
      "support": "SUPPORTED",
      "required": {
        "standard_attributes": ["ID", "STANDARD_PRICE", "STOCK"],
        "custom_attributes": []
      }
    }
  }
}

A channel that runs several sales channels can price and stock its offers per sub-channel, instead of once per store. The channel declares that in three nodes, one for each kind of data: standard_prices, discount_prices, and stock_quantities.

Each node holds a lifecycle, with two values:

• PER_STORE: one value for the whole store. This is the default, and a node you leave out gets it.
• PER_SUB_CHANNEL: one value for each sub-channel of the store.

A store that carries no sub-channel keeps store-level values, whatever the lifecycle declares. Read Sub-channels for how a store gets them.

Declare discount_prices as PER_SUB_CHANNEL only together with standard_prices, because a per-sub-channel discount price follows the standard price.

standard_prices and discount_prices take a second node, per_store_default, which Mirakl Connect reads only when the lifecycle is PER_SUB_CHANNEL. Its support field declares what the channel does with a store-level price alongside the per-sub-channel prices:

• REQUIRED: the channel needs both. Mirakl Connect drops the event when it has a sub-channel price to send and no store-level price to send with it.
• OPTIONAL: the channel accepts both. Mirakl Connect sends the store-level price whenever it holds one.
• UNSUPPORTED: the channel takes the per-sub-channel price alone. Mirakl Connect sends the store-level price as IGNORE.

stock_quantities takes no per_store_default, because stock has no store-level fallback. When its lifecycle is PER_SUB_CHANNEL, the breakdown arrives in the sub-channel block alone, and the store-level stock arrives as IGNORE.

In the configuration below, the two prices and the stock are all per sub-channel, the channel needs a store-level standard price, and it accepts a store-level discount price without needing one:

{
  "standard_prices": {
    "lifecycle": "PER_SUB_CHANNEL",
    "per_store_default": { "support": "REQUIRED" }
  },
  "discount_prices": {
    "lifecycle": "PER_SUB_CHANNEL",
    "per_store_default": { "support": "OPTIONAL" }
  },
  "stock_quantities": {
    "lifecycle": "PER_SUB_CHANNEL"
  }
}

Offers priced and stocked per sub-channel documents the events this lifecycle produces.

Some channels accept a product only together with its related products. To receive related products as one group, set emit_group_of_products in the behaviors node. It takes one of two values:

• VARIANT_GROUP_CODE: Mirakl Connect groups the products that share a variant group code.
• BRAND: Mirakl Connect groups the products of the same brand in the store.

Leave emit_group_of_products out, or set it to null, to receive each product on its own. This is the default.

{
  "behaviors": {
    "emit_group_of_products": "VARIANT_GROUP_CODE"
  }
}

Handle grouped products documents how a group arrives on the product events.

• Taxonomy: register the product types and the taxonomy rules that shape the channel products.
• Catalog flow: once the catalog configuration and the taxonomy are complete, the seller synchronizes the catalog to the channel.
• Create and update offers: how the offer events this configuration gates are handled.
• Business use cases: where this configuration sits among the flows, and what waits on it.