Troubleshoot issues related to Merchant Promotions API

This page describes how to troubleshoot issues related to the Merchant Promotions 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