Programmatic Orders Fail to Push to Google Ad Manager with buyerPermissionType Error

Problem

When attempting to push Programmatic Guaranteed (PG) or other programmatic orders to Google Ad Manager (GAM), the operation fails with the following error:

NotNullError.NULL @ [0].buyerPermissionType

This error indicates that GAM is expecting a required field buyerPermissionType on the Proposal Line Item, but the value is missing or null in the payload sent by CloudSense.

Root Cause

This issue typically occurs after Google Ad Manager API version migrations, specifically when CloudSense services are upgraded to use newer GAM API versions.

Background:
- In older GAM API versions (e.g., v202411 and earlier), the buyerPermissionType field was optional or not enforced
- In newer GAM API versions (e.g., v202508 and later), buyerPermissionType is a required field for Proposal Line Items
- The field determines who is allowed to traffic or transact the deal on the buyer side, which is especially relevant for bidder-level deal sharing

If your fulfilmentStrategy.json mapping file does not include the buyerPermissionType mapping, GAM will reject the push with a NotNullError because a non-nullable field is effectively unset.

buyerPermissionType Values:
- NEGOTIATOR_ONLY: Use for the classic one-buyer (agency/advertiser) permissioning model (most common)
- BIDDER: Use only if you intend bidder-level permissioning (deal sharing across seats on the same DSP)

Resolution Steps

Step 1: Verify Your GAM API Version

1. Check which GAM API version your CloudSense services are currently using:
2. Contact your CloudSense administrator or check recent service update notifications

3. If you recently experienced a service migration or upgrade, note the new API version

4. Review the GAM API documentation for your version:

5. Navigate to: https://developers.google.com/ad-manager/api/reference/v[VERSION]/ProposalLineItemService.ProposalLineItem
6. Replace [VERSION] with your API version (e.g., v202508)
7. Check if buyerPermissionType is listed as a required field

Step 2: Update the Fulfilment Strategy Mapping File

1. Locate the fulfilmentStrategy.json file in your Salesforce org:
2. Navigate to Setup > Static Resources
3. Search for your GAM fulfilment strategy static resource (e.g., "FulfilmentStrategy_GAM", "FulfilmentStrategy_Programmatic")

4. Download and open the JSON file

5. Find the proposalLineItem.mapExpression block:

{
  "proposalLineItem": {
    "enabled": true,
    "engine": "JavaScript",
    "mapExpression": "{\n  // ... existing mappings ...\n}"
  }
}

1. Add the buyerPermissionType mapping to the mapExpression:

dfpProposalLineItem.setBuyerPermissionType(dfp.BuyerPermissionType.NEGOTIATOR_ONLY);

Complete example:

{
  "proposalLineItem": {
    "enabled": true,
    "engine": "JavaScript",
    "mapExpression": "{\n  dfpProposalLineItem.setName(fulfilmentItem.getName());\n  dfpProposalLineItem.setStartDateTime(fulfilmentItem.getStartDate());\n  dfpProposalLineItem.setEndDateTime(fulfilmentItem.getEndDate());\n  dfpProposalLineItem.setBuyerPermissionType(dfp.BuyerPermissionType.NEGOTIATOR_ONLY);\n  // ... other mappings ...\n}"
  }
}

1. Important notes:
2. Use NEGOTIATOR_ONLY for standard agency/advertiser permissioning (recommended for most implementations)
3. Use BIDDER only if your network has bidder-level permissioning enabled and you need deal sharing across DSP seats
4. Keep the value consistent across all proposal line items in the same proposal

Step 3: Redeploy the Fulfilment Strategy

1. Upload the updated JSON file to the Static Resource in Salesforce:
2. Go to Setup > Static Resources
3. Edit the existing static resource
4. Upload the modified fulfilmentStrategy.json file

5. Save the static resource

6. Clear any caching (if applicable in your environment):

7. Some implementations may cache the fulfilment strategy
8. Restart any relevant services or clear browser cache if needed

Step 4: Retry the Fulfilment Push

1. Open the affected Fulfilment record in Salesforce

2. Click "Push to Ad Server" to retry the push operation

3. Monitor the Outgoing Message log:

4. Navigate to the related Outgoing Message record
5. Check the Notes & Attachments section for the JSON payload file

6. Verify that buyerPermissionType is present in the payload with value "NEGOTIATOR_ONLY" or "BIDDER"

7. Verify in Google Ad Manager:

8. Log in to GAM
9. Navigate to the Proposal Line Item
10. Confirm the Buyer Permission Type is correctly set

Verification

After completing the resolution steps:

1. Check the Outgoing Message JSON payload:
2. Download the JSON file from the Outgoing Message record

3. Search for "buyerPermissionType" and confirm it has a valid value:
   json { "buyerPermissionType": "NEGOTIATOR_ONLY" }

4. Verify successful push:

5. Check that the Outgoing Message status is "Success"

6. No API fault errors are present

7. Confirm in GAM:

8. Log in to Google Ad Manager
9. Navigate to Delivery > Proposals
10. Open the Proposal Line Item
11. Verify the Buyer Permission Type field is populated

Prevention

To prevent this issue in future GAM API version migrations:

• Subscribe to GAM API deprecation notices from Google to stay informed of upcoming API changes
• Review GAM API release notes when CloudSense services are upgraded to new API versions
• Test fulfilment pushes in a sandbox environment after any GAM API version migration
• Maintain a checklist of required GAM fields for each API version
• Document all customizations to fulfilment strategy files for future reference
• Implement validation in your fulfilment strategy to ensure all required fields are present before pushing to GAM

Important Notes

• This issue affects Programmatic Guaranteed (PG) orders and potentially other programmatic order types
• The buyerPermissionType field was introduced as required in GAM API v202508 (and may vary by version)
• If you omit this field in setups with publisher-managed creatives or bidder-level permissioning, API validation will fail
• Changes to fulfilmentStrategy.json require redeploying the Static Resource
• The field must be set consistently across all proposal line items in the same proposal
• For most implementations, NEGOTIATOR_ONLY is the correct value unless you specifically need bidder-level deal sharing