Troubleshoot issues related to Promotions sub-API

  • This page provides troubleshooting guidance for issues encountered when using the Merchant Promotions API, specifically the accounts.promotions.insert request.

  • When inserting a promotion, ensure all required fields are included, such as promotionId, contentLanguage, redemptionChannel, and others detailed in the documentation.

  • To avoid errors related to promotion effective time periods, make sure that the promotionDisplayTimePeriod values are logically set to be before or equal to the promotionEffectiveTimePeriod values, and that they follow the RFC3339 UTC format (e.g., yyyy-mm-ddThh:mm:ssZ).

  • Depending on the couponValueType used, certain fields must be specified; for example, minimumPurchaseQuantity is required for BUY_M_GET_N_PERCENT_OFF or BUY_M_GET_N_MONEY_OFF, and moneyOffAmount for MONEY_OFF, and freeGiftDescription for FREE_GIFT.

  • Free shipping promotions (FREE_SHIPPING_STANDARD, FREE_SHIPPING_OVERNIGHT, or FREE_SHIPPING_TWO_DAY) are only supported for online redemptions, meaning the redemptionChannel should be set to ONLINE, not IN_STORE; also make sure that contentLanguage and targetCountry matches the data source.

This page describes how to troubleshoot issues related to the Promotions sub-API.

Create a promotion

When using the accounts.promotions.insert request to insert a promotion, make sure that you have included all the required fields in your request body. The following fields are required:

  • promotion.promotionId
  • promotion.contentLanguage
  • promotion.redemptionChannel
  • promotion.targetCountry
  • promotion.attributes.longTitle
  • promotion.attributes.promotionEffectiveTimePeriod.startTime
  • promotion.attributes.promotionEffectiveTimePeriod.endTime
  • promotion.attributes.promotionDestinations
  • promotion.attributes.couponValueType
  • promotion.attributes.offerType
  • promotion.attributes.productApplicability
  • promotion.attributes.promotionUrl

Invalid promotion effective time period

If you provide invalid promotion effective dates in your accounts.promotions.insert request, you will see the following error message:

Invalid value at 'promotion.attributes.promotion_effective_time_period.start_time'

To resolve this error, make sure that the value provided for the promotionDisplayTimePeriod.startTime field is the same or before the value provided for the promotionEffectiveTimePeriod.startTime field. Also make sure that the value provided for the promotionDisplayTimePeriod.endTime field is the same or before the value provided for the promotionEffectiveTimePeriod.endTime field.

The values for the startTime and endTime fields must be in the RFC3339 UTC format, that is yyyy-mm-ddThh:mm:ssZ. For example, 2024-08-15T18:20:20Z.

Minimum purchase quantity not specified

If your attributes.couponValueType is BUY_M_GET_N_PERCENT_OFF or BUY_M_GET_N_MONEY_OFF, you must provide a value for the attributes.minimumPurchaseQuantity field in your accounts.promotions.insert request.

If you don't provide a value for the attributes.minimumPurchaseQuantity field in your accounts.promotions.insert request, you will see the following error message:

[minimumPurchaseQuantity] Missing benefit or restriction attributes for its type

To resolve this error, make sure that you provide a value for the minimumPurchaseQuantity field in your request.

Money off amount not specified

If the value of your attributes.couponValueType field is MONEY_OFF, you must provide a value for the attributes.moneyOffAmount field in your accounts.promotions.insert request.

If you don't provide a value for the attributes.moneyOffAmount field in your accounts.promotions.insert request, you will see the following error message:

[moneyOffAmount] Missing benefit or restriction attributes for its type

To resolve this error, make sure that you provide a value for the attributes.moneyOffAmount field in your request. The amount must be in micro.

Description of free gift not specified

If the value of your attributes.couponValueType field is FREE_GIFT, you must provide a value for the attributes.freeGiftDescription field in your accounts.promotions.insert request.

If you don't provide a value for the attributes.freeGiftDescription field in your accounts.promotions.insert request, you will see the following error message:

[freeGiftDescription] Missing benefit or restriction attributes for its type

To resolve this error, make sure that you provide a value for the attributes.freeGiftDescription field in your request.

Free shipping not supported for local promotions

If the value of the redemptionChannel field is IN_STORE and the value of the attributes.couponValueType field is FREE_SHIPPING_STANDARD, FREE_SHIPPING_OVERNIGHT, or FREE_SHIPPING_TWO_DAY, you will see the following error message:

[shippingServiceNames] Free shipping types are not supported for local promotions

To resolve this error, make sure that the value of the redemptionChannel field is ONLINE.

Redemption channel not specified

If the value of the redemptionChannel field isn't specified in your accounts.promotions.insert request, you will see the following error message:

[redemptionChannel] Required parameter: redemptionChannel

To resolve this error, make sure that you provide a value for the redemptionChannel field in your request.

The contentLanguage field of the promotion and the data source don't match

If the value of the contentLanguage field isn't the same as the value of the contentLanguage field of the promotions data source you are using in your accounts.promotions.insert request, you will see the following error message:

[promotion] Could not find the proper data target for the provided feedLabel and contentLanguage

To resolve this error, make sure that the value of the contentLanguage field is the same as the value of the contentLanguage field of the promotions data source you are using.

You will also see this error if the value of the targetCountry isn't the same as the value of the targetCountry field of the promotions data source you are using.

Learn more