> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # SelectIncentive # Package: googleAds # Namespace: AccountService # Method link: https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-account-v1/select-incentive.md ## Permission Scopes: Manage google ads campaigns: SCOPE.PROMOTE.MANAGE-GOOGLE-ADS ## Introduction Records the user's Google Ads acquisition incentive choice in the database before checkout. Does not call the Google Ads API. The recorded incentive is applied automatically after the account's budget is assigned. Use ApplyIncentive to apply it immediately on an existing account. --- ## REST API ### Schema ``` Method: selectIncentive Description: Records the user's Google Ads acquisition incentive choice in the database before checkout. Does not call the Google Ads API. The recorded incentive is applied automatically after the account's budget is assigned. Use ApplyIncentive to apply it immediately on an existing account. URL: https://www.wixapis.com/_serverless/pa-google/v1/accounts/current-site/incentives/select Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: incentiveId Method parameters: param name: incentiveId | type: incentiveId | description: Incentive GUID returned by `SuggestionsService.GetIncentives`. | required: true | validation: maxLength 1000 Return type: SelectIncentiveResponse - name: account | type: Account | description: The account with the updated `selectedIncentiveId` persisted. - name: id | type: string | description: Account GUID. | validation: format GUID - name: googleAccountId | type: string | description: Google Ads customer account GUID. - name: googleManagerAccountId | type: string | description: Google Ads manager account GUID that owns this account. - name: googleManagerSubAccountId | type: string | description: Google Ads manager sub-account GUID. - name: googleBillingSetupId | type: string | description: Google Ads billing setup GUID. Not set for test accounts. - name: createdDate | type: string | description: Date and time the account was created. | validation: format date-time - name: updatedDate | type: string | description: Date and time the account was last updated. | validation: format date-time - name: premiumSubscriptionId | type: string | description: GUID of the premium subscription associated with this account. | validation: format GUID - name: currentBudget | type: Money | description: Remaining ad budget on the account. Positive values indicate available credits; negative values indicate outstanding debt that has not yet been charged. - name: value | type: string | description: Monetary amount. Decimal string with a period as a decimal separator (e.g., 3.99). Optionally, a single (-), to indicate that the amount is negative. | validation: format DECIMAL_VALUE, decimalValue {"maxScale":2} - name: currency | type: string | description: Currency code. Must be valid ISO 4217 currency code (e.g., USD). | validation: format CURRENCY - name: formattedValue | type: string | description: Monetary amount. Decimal string in local format (e.g., 1 000,30). Optionally, a single (-), to indicate that the amount is negative. | validation: maxLength 1000 - name: spentBudget | type: Money | description: Total amount of the budget that has been spent on ads. - name: paymentStatus | type: PaymentStatusEnum | description: Payment status of the account. - name: status | type: PaymentStatus | description: Status of the account's payment. - enum: - UNSPECIFIED: Not specified. - PENDING_PAYMENT: Payment is pending. - PENDING_SUBSCRIPTION: Subscription is pending. - PAID: Paid, and the subscription is confirmed. - CUSTOM_CHARGE: Account uses a custom charge (pay-as-you-go) model instead of a fixed subscription. - name: latestInvoiceId | type: string | description: GUID of the most recent invoice generated for this account. | validation: format GUID - name: currency | type: string | description: Three-letter currency code in ISO-4217 alphabetic format. This is the currency selected by the site owner and may differ from the currency used by Google Ads directly. See `budgetInSupportedCurrency`. - name: budgetInSupportedCurrency | type: Money | description: The current ad budget converted to a currency supported directly by Google Ads (USD, EUR, GBP, or JPY). This may differ from `currency` when the site owner selected a currency not natively supported by Google Ads. - name: couponInfo | type: CouponInfo | description: Legacy coupon information assigned to the account. Use `appliedIncentive` for the full incentive lifecycle. - name: customerId | type: string | description: Google Ads customer account GUID associated with this coupon. - name: accountName | type: string | description: Google Ads account name. - name: couponCode | type: string | description: Unique coupon code returned by Google Ads when the incentive was applied. - name: status | type: CouponStatus | description: Current status of the coupon. - enum: - REDEEMED: Coupon has been redeemed. This is the initial status; the account is eligible but has not yet met the spend requirements. - FULFILLED: Spend requirements have been met and the reward is being processed. - EXPIRED: Coupon expired before the spend requirements were met. - REWARD_GRANTED: Reward has been granted and is available for use. - INVALIDATED: Coupon was marked as invalid after redemption. - name: redemptionDate | type: string | description: Date when the account became eligible for the coupon (coupon redemption date). | validation: format date-time - name: expirationDate | type: string | description: Date until which spend is counted toward the coupon match requirements. | validation: format date-time - name: rewardGrantDate | type: string | description: Date when the coupon reward was granted to the account. | validation: format date-time - name: redemptionTimeMs | type: string | description: Same date as `redemptionDate`, represented as a Unix timestamp in milliseconds. | validation: format date-time - name: expirationTimeMs | type: string | description: Same date as `expirationDate`, represented as a Unix timestamp in milliseconds. | validation: format date-time - name: rewardGrantTimeMs | type: string | description: Same date as `rewardGrantDate`, represented as a Unix timestamp in milliseconds. | validation: format date-time - name: maxDaysToReward | type: integer | description: Total number of days over which the spend match is calculated. Equivalent to the number of days between `redemptionDate` and `expirationDate`. | validation: format int32 - name: daysToReward | type: integer | description: Days remaining to fulfill the spend match requirements. Returns `0` when `expirationDate` has passed. | validation: format int32 - name: maxAmount | type: Money | description: Maximum reward amount that can be granted for this coupon. - name: amountGranted | type: Money | description: Actual reward amount that was granted. - name: rewardExpirationDate | type: string | description: Date when the granted reward expires. | validation: format date-time - name: rewardExpirationTimeMs | type: string | description: Same date as `rewardExpirationDate`, represented as a Unix timestamp in milliseconds. | validation: format date-time - name: merchantCenterAccountId | type: string | description: GUID of the Google Merchant Center account linked to this Google Ads account. - name: merchantCenterAccountLinkStatus | type: MerchantCenterLinkStatusEnum | description: Link status between this account and the associated Google Merchant Center account. - name: status | type: MerchantCenterLinkStatus | description: The Merchant Center link status. - enum: - UNSPECIFIED: Unknown link status. - UNKNOWN: Link status is not recognized in this version. - ENABLED: The Merchant Center account is linked and active. - PENDING: A link request has been sent and is awaiting approval from the Merchant Center account owner. - name: wixServiceFeePercentage | type: integer | description: Percentage of the subscription amount that Wix retains as a service fee. | validation: format int32 - name: boosterSubscriptions | type: BoosterSubscriptions | description: Booster subscription details for this account. - name: subscriptions | type: array | description: Booster subscriptions for this account. | validation: maxItems 1000 - name: premiumSubscriptionId | type: string | description: Premium subscription GUID for this booster subscription. - name: invoiceId | type: string | description: GUID of the most recent invoice for this booster subscription. - name: currencyConversionInfo | type: Money | description: The booster subscription's contribution, converted to the account's currency. - name: wixServiceFeePercentage | type: integer | description: Percentage of the booster subscription amount that Wix retains as a service fee. | validation: format int32 - name: accountStatus | type: AccountStatus | description: Current status of the account. - enum: - ACTIVE: The account is active. - BLOCKED: Account is blocked, and cannot be used for creating new campaigns. - SUSPENDED: The account is suspended. - CANCELED: The account is canceled or deactivated. - name: customChargeSubscription | type: boolean | description: Whether the account uses a custom charge (pay-as-you-go) subscription model instead of a fixed premium subscription. - name: blockReason | type: BlockReasonEnum | description: Reason the account is blocked by Wix, if applicable. Set by fraud, unpaid balance, or chargeback handlers. Cleared when the block is lifted. - name: reason | type: BlockReason | description: The block reason. - enum: - UNSPECIFIED: Account is not blocked by Wix. The account may still be suspended or canceled by Google independently. - FRAUD: Account was blocked because a fraud flag was raised. - UNPAID_BALANCE: Account was blocked due to an unpaid balance from a failed recurring custom charge. - CHARGEBACK: Account was blocked due to a chargeback dispute filed with the bank. - name: blockedDate | type: string | description: Date and time the account was blocked. Set together with `blockReason` and cleared when the block is lifted. | validation: format date-time - name: appliedIncentive | type: AppliedIncentive | description: Details of the applied Google Ads promotional incentive, enriched from the Google Ads API. Tracks the lifecycle from `REDEEMED` through `FULFILLED` to `REWARD_GRANTED`. - name: resourceName | type: string | description: Google Ads resource name for this incentive. | validation: maxLength 1000 - name: couponCode | type: string | description: Coupon code returned by Google when the incentive was applied. | validation: maxLength 1000 - name: incentiveState | type: AppliedIncentiveState | description: Current lifecycle state of the applied incentive. - enum: - UNSPECIFIED: Unknown incentive state. - UNKNOWN: Incentive state is not recognized in this version. - REDEEMED: The incentive has been redeemed but the spend requirements are not yet met. - FULFILLED: The spend requirements have been met but the reward has not yet been granted. - REWARD_GRANTED: The reward has been granted to the account. - EXPIRED: The incentive expired before the spend requirements were met. - REWARD_EXPIRED: The granted reward has expired without being fully used. - INVALIDATED: The incentive was marked as invalid after redemption. - REWARD_EXHAUSTED: The granted reward has been fully used. - name: redemptionDate | type: string | description: UTC date when the incentive was redeemed. | validation: format date-time - name: fulfillmentExpirationDate | type: string | description: UTC date by which the incentive requirements must be fulfilled. | validation: format date-time - name: rewardGrantDate | type: string | description: UTC date when the incentive reward was granted. | validation: format date-time - name: rewardExpirationDate | type: string | description: UTC date when the granted reward expires. | validation: format date-time - name: rewardAmount | type: Money | description: Maximum potential reward amount. - name: grantedAmount | type: Money | description: Amount of the reward that was granted. - name: requiredMinSpend | type: Money | description: Minimum amount that must be spent to fulfill the coupon requirements. - name: currentSpendTowardsFulfillment | type: Money | description: Current amount spent towards the fulfillment requirements. - name: rewardBalanceRemaining | type: Money | description: Remaining balance of the granted reward. - name: incentiveId | type: string | description: Incentive GUID returned by `SuggestionsService.GetIncentives`. | validation: maxLength 1000 - name: creationDate | type: string | description: UTC date when the incentive was applied. | validation: format date-time - name: incentiveApplicationStatus | type: IncentiveApplicationStatusEnum | description: Status of the incentive application process for this account. - name: status | type: IncentiveApplicationStatus | description: The incentive application status. - enum: - UNSPECIFIED: Unknown incentive application status. - UNKNOWN: Incentive application status is not recognized in this version. - APPLIED: The incentive was successfully applied. - FAILED_TO_APPLY: The incentive could not be applied after all retry attempts were exhausted. - name: selectedIncentiveId | type: string | description: Incentive GUID selected by the user before checkout, to be applied automatically after the account's budget is assigned. | validation: maxLength 1000 Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INCENTIVE_FAILED_TO_APPLY | Description: The incentive could not be applied after all retry attempts were exhausted. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INCENTIVE_ALREADY_APPLIED | Description: An incentive has already been applied to this account. ``` ### Examples ### Select Incentive ```curl curl -X POST \ 'https://www.wixapis.com/google-ads/v1/accounts/current-site/incentives/select' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "incentiveId": "incentive-promo-2024-usd-500" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.promoteGoogleAds.accounts.selectIncentive(incentiveId) Description: Records the user's Google Ads acquisition incentive choice in the database before checkout. Does not call the Google Ads API. The recorded incentive is applied automatically after the account's budget is assigned. Use ApplyIncentive to apply it immediately on an existing account. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: incentiveId Method parameters: param name: incentiveId | type: string | description: Incentive GUID returned by `SuggestionsService.GetIncentives`. | required: true | validation: maxLength 1000 Return type: PROMISE - name: account | type: Account | description: The account with the updated `selectedIncentiveId` persisted. - name: _id | type: string | description: Account GUID. | validation: format GUID - name: googleAccountId | type: string | description: Google Ads customer account GUID. - name: googleManagerAccountId | type: string | description: Google Ads manager account GUID that owns this account. - name: googleManagerSubAccountId | type: string | description: Google Ads manager sub-account GUID. - name: googleBillingSetupId | type: string | description: Google Ads billing setup GUID. Not set for test accounts. - name: _createdDate | type: Date | description: Date and time the account was created. - name: _updatedDate | type: Date | description: Date and time the account was last updated. - name: premiumSubscriptionId | type: string | description: GUID of the premium subscription associated with this account. | validation: format GUID - name: currentBudget | type: Money | description: Remaining ad budget on the account. Positive values indicate available credits; negative values indicate outstanding debt that has not yet been charged. - name: value | type: string | description: Monetary amount. Decimal string with a period as a decimal separator (e.g., 3.99). Optionally, a single (-), to indicate that the amount is negative. | validation: format DECIMAL_VALUE, decimalValue {"maxScale":2} - name: currency | type: string | description: Currency code. Must be valid ISO 4217 currency code (e.g., USD). | validation: format CURRENCY - name: formattedValue | type: string | description: Monetary amount. Decimal string in local format (e.g., 1 000,30). Optionally, a single (-), to indicate that the amount is negative. | validation: maxLength 1000 - name: spentBudget | type: Money | description: Total amount of the budget that has been spent on ads. - name: paymentStatus | type: PaymentStatusEnum | description: Payment status of the account. - name: status | type: PaymentStatus | description: Status of the account's payment. - enum: - UNSPECIFIED: Not specified. - PENDING_PAYMENT: Payment is pending. - PENDING_SUBSCRIPTION: Subscription is pending. - PAID: Paid, and the subscription is confirmed. - CUSTOM_CHARGE: Account uses a custom charge (pay-as-you-go) model instead of a fixed subscription. - name: latestInvoiceId | type: string | description: GUID of the most recent invoice generated for this account. | validation: format GUID - name: currency | type: string | description: Three-letter currency code in ISO-4217 alphabetic format. This is the currency selected by the site owner and may differ from the currency used by Google Ads directly. See `budgetInSupportedCurrency`. - name: budgetInSupportedCurrency | type: Money | description: The current ad budget converted to a currency supported directly by Google Ads (USD, EUR, GBP, or JPY). This may differ from `currency` when the site owner selected a currency not natively supported by Google Ads. - name: couponInfo | type: CouponInfo | description: Legacy coupon information assigned to the account. Use `appliedIncentive` for the full incentive lifecycle. - name: customerId | type: string | description: Google Ads customer account GUID associated with this coupon. - name: accountName | type: string | description: Google Ads account name. - name: couponCode | type: string | description: Unique coupon code returned by Google Ads when the incentive was applied. - name: status | type: CouponStatus | description: Current status of the coupon. - enum: - REDEEMED: Coupon has been redeemed. This is the initial status; the account is eligible but has not yet met the spend requirements. - FULFILLED: Spend requirements have been met and the reward is being processed. - EXPIRED: Coupon expired before the spend requirements were met. - REWARD_GRANTED: Reward has been granted and is available for use. - INVALIDATED: Coupon was marked as invalid after redemption. - name: redemptionDate | type: Date | description: Date when the account became eligible for the coupon (coupon redemption date). - name: expirationDate | type: Date | description: Date until which spend is counted toward the coupon match requirements. - name: rewardGrantDate | type: Date | description: Date when the coupon reward was granted to the account. - name: redemptionTimeMs | type: Date | description: Same date as `redemptionDate`, represented as a Unix timestamp in milliseconds. - name: expirationTimeMs | type: Date | description: Same date as `expirationDate`, represented as a Unix timestamp in milliseconds. - name: rewardGrantTimeMs | type: Date | description: Same date as `rewardGrantDate`, represented as a Unix timestamp in milliseconds. - name: maxDaysToReward | type: integer | description: Total number of days over which the spend match is calculated. Equivalent to the number of days between `redemptionDate` and `expirationDate`. | validation: format int32 - name: daysToReward | type: integer | description: Days remaining to fulfill the spend match requirements. Returns `0` when `expirationDate` has passed. | validation: format int32 - name: maxAmount | type: Money | description: Maximum reward amount that can be granted for this coupon. - name: amountGranted | type: Money | description: Actual reward amount that was granted. - name: rewardExpirationDate | type: Date | description: Date when the granted reward expires. - name: rewardExpirationTimeMs | type: Date | description: Same date as `rewardExpirationDate`, represented as a Unix timestamp in milliseconds. - name: merchantCenterAccountId | type: string | description: GUID of the Google Merchant Center account linked to this Google Ads account. - name: merchantCenterAccountLinkStatus | type: MerchantCenterLinkStatusEnum | description: Link status between this account and the associated Google Merchant Center account. - name: status | type: MerchantCenterLinkStatus | description: The Merchant Center link status. - enum: - UNSPECIFIED: Unknown link status. - UNKNOWN: Link status is not recognized in this version. - ENABLED: The Merchant Center account is linked and active. - PENDING: A link request has been sent and is awaiting approval from the Merchant Center account owner. - name: wixServiceFeePercentage | type: integer | description: Percentage of the subscription amount that Wix retains as a service fee. | validation: format int32 - name: boosterSubscriptions | type: BoosterSubscriptions | description: Booster subscription details for this account. - name: subscriptions | type: array | description: Booster subscriptions for this account. | validation: maxItems 1000 - name: premiumSubscriptionId | type: string | description: Premium subscription GUID for this booster subscription. - name: invoiceId | type: string | description: GUID of the most recent invoice for this booster subscription. - name: currencyConversionInfo | type: Money | description: The booster subscription's contribution, converted to the account's currency. - name: wixServiceFeePercentage | type: integer | description: Percentage of the booster subscription amount that Wix retains as a service fee. | validation: format int32 - name: accountStatus | type: AccountStatus | description: Current status of the account. - enum: - ACTIVE: The account is active. - BLOCKED: Account is blocked, and cannot be used for creating new campaigns. - SUSPENDED: The account is suspended. - CANCELED: The account is canceled or deactivated. - name: customChargeSubscription | type: boolean | description: Whether the account uses a custom charge (pay-as-you-go) subscription model instead of a fixed premium subscription. - name: blockReason | type: BlockReasonEnum | description: Reason the account is blocked by Wix, if applicable. Set by fraud, unpaid balance, or chargeback handlers. Cleared when the block is lifted. - name: reason | type: BlockReason | description: The block reason. - enum: - UNSPECIFIED: Account is not blocked by Wix. The account may still be suspended or canceled by Google independently. - FRAUD: Account was blocked because a fraud flag was raised. - UNPAID_BALANCE: Account was blocked due to an unpaid balance from a failed recurring custom charge. - CHARGEBACK: Account was blocked due to a chargeback dispute filed with the bank. - name: blockedDate | type: Date | description: Date and time the account was blocked. Set together with `blockReason` and cleared when the block is lifted. - name: appliedIncentive | type: AppliedIncentive | description: Details of the applied Google Ads promotional incentive, enriched from the Google Ads API. Tracks the lifecycle from `REDEEMED` through `FULFILLED` to `REWARD_GRANTED`. - name: resourceName | type: string | description: Google Ads resource name for this incentive. | validation: maxLength 1000 - name: couponCode | type: string | description: Coupon code returned by Google when the incentive was applied. | validation: maxLength 1000 - name: incentiveState | type: AppliedIncentiveState | description: Current lifecycle state of the applied incentive. - enum: - UNSPECIFIED: Unknown incentive state. - UNKNOWN: Incentive state is not recognized in this version. - REDEEMED: The incentive has been redeemed but the spend requirements are not yet met. - FULFILLED: The spend requirements have been met but the reward has not yet been granted. - REWARD_GRANTED: The reward has been granted to the account. - EXPIRED: The incentive expired before the spend requirements were met. - REWARD_EXPIRED: The granted reward has expired without being fully used. - INVALIDATED: The incentive was marked as invalid after redemption. - REWARD_EXHAUSTED: The granted reward has been fully used. - name: redemptionDate | type: Date | description: UTC date when the incentive was redeemed. - name: fulfillmentExpirationDate | type: Date | description: UTC date by which the incentive requirements must be fulfilled. - name: rewardGrantDate | type: Date | description: UTC date when the incentive reward was granted. - name: rewardExpirationDate | type: Date | description: UTC date when the granted reward expires. - name: rewardAmount | type: Money | description: Maximum potential reward amount. - name: grantedAmount | type: Money | description: Amount of the reward that was granted. - name: requiredMinSpend | type: Money | description: Minimum amount that must be spent to fulfill the coupon requirements. - name: currentSpendTowardsFulfillment | type: Money | description: Current amount spent towards the fulfillment requirements. - name: rewardBalanceRemaining | type: Money | description: Remaining balance of the granted reward. - name: incentiveId | type: string | description: Incentive GUID returned by `SuggestionsService.GetIncentives`. | validation: maxLength 1000 - name: creationDate | type: Date | description: UTC date when the incentive was applied. - name: incentiveApplicationStatus | type: IncentiveApplicationStatusEnum | description: Status of the incentive application process for this account. - name: status | type: IncentiveApplicationStatus | description: The incentive application status. - enum: - UNSPECIFIED: Unknown incentive application status. - UNKNOWN: Incentive application status is not recognized in this version. - APPLIED: The incentive was successfully applied. - FAILED_TO_APPLY: The incentive could not be applied after all retry attempts were exhausted. - name: selectedIncentiveId | type: string | description: Incentive GUID selected by the user before checkout, to be applied automatically after the account's budget is assigned. | validation: maxLength 1000 Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INCENTIVE_FAILED_TO_APPLY | Description: The incentive could not be applied after all retry attempts were exhausted. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INCENTIVE_ALREADY_APPLIED | Description: An incentive has already been applied to this account. ``` ### Examples ### Select a Google Ads acquisition incentive ```javascript import { accounts } from '@wix/promote-google-ads'; const response = await accounts.selectIncentive('incentive-promo-2024-usd-500'); /* Promise resolves to: * { * "_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", * "googleAccountId": "123-456-7890", * "currency": "USD", * "accountStatus": "ACTIVE", * "selectedIncentiveId": "incentive-promo-2024-usd-500", * "paymentStatus": "PAID", * "currentBudget": { "value": "50.00", "currency": "USD" }, * "_createdDate": "2024-03-15T10:30:00.000Z", * "_updatedDate": "2024-03-16T14:00:00.000Z" * } */ ``` ### selectIncentive (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { accounts } from '@wix/promote-google-ads'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { accounts }, // Include the auth strategy and host as relevant }); async function selectIncentive(incentiveId) { const response = await myWixClient.accounts.selectIncentive(incentiveId); }; ``` ---