You can use the [Display \& Video 360 API](https://developers.google.com/display-video/api/v1beta2) to manage [custom bidding](https://support.google.com/displayvideo/answer/9723477)
implementations. You can create custom bidding algorithms, upload and verify
individual scripts, and assign a specific algorithm to a resource as its bidding
strategy.

This page describes how to create, update, and assign custom bidding algorithms
with the Display \& Video 360 API. Each section provides a code sample.

## Create a Custom Bidding Algorithm

A [`CustomBiddingAlgorithm`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm) object represents an individual
algorithm that you can assign to a line item for use in its bid strategy. This
object has details on the algorithm such as its
[`customBiddingAlgorithmType`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm.FIELDS.custom_bidding_algorithm_type),
[`entityStatus`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm.FIELDS.entity_status) and
[`customBiddingAlgorithmState`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm.FIELDS.custom_bidding_algorithm_state). You can create
[`CustomBiddingScript`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts#CustomBiddingScript) objects as child resources for the algorithm
to use.

> [!NOTE]
> **Note:** This guide focuses on script-based custom bidding algorithms. Algorithms created in Ads Data Hub or through the Display \& Video 360 UI Goal Builder tool can be retrieved and assigned, but not fully managed.

Here's an example of how to create a script-based custom bidding
algorithm:

### Python

```python
# Create a custom bidding algorithm object.
custom_bidding_algorithm_obj = {
    'advertiserId': advertiser-id,
    'displayName': display-name,
    'entityStatus': 'ENTITY_STATUS_ACTIVE',
    'customBiddingAlgorithmType': 'SCRIPT_BASED'
}

# Create the custom bidding algorithm.
response = service.customBiddingAlgorithms().create(
    body=algorithm_obj
).execute()

# Display the new custom bidding algorithm.
print(f'The following Custom Bidding Algorithm was created: {response}')
```

### Manage algorithm access

Custom bidding algorithms can be owned by a partner or an advertiser. Algorithms
owned by a partner can be accessed and modified by that partner and any child
advertisers listed in the [`sharedAdvertiserIds`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm.FIELDS.shared_advertiser_ids) field.
Algorithms owned by an advertiser can be accessed and modified by that
advertiser and its parent partner, but cannot be shared with other advertisers.

> [!NOTE]
> **Note:** When creating a custom bidding algorithm, you must have read/write access to the partner or advertiser which you assign as the owner.

If you're only using the algorithm for a single advertiser, assign the
advertiser as the owner with the [`advertiserId`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm.FIELDS.advertiser_id) field.
Otherwise, assign the parent partner of the advertisers as the owner with the
[`partnerId`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm.FIELDS.partner_id) field, and give the advertisers access with the
[`sharedAdvertiserIds`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm.FIELDS.shared_advertiser_ids) field.

## Upload a script

Once you've created a custom bidding algorithm, create a script for that
algorithm to use. Script-based custom bidding algorithms employ user-provided
[scripts](https://support.google.com/displayvideo/answer/9728993) to evaluate the worth of an impression.
Samples of [simple scripts](https://support.google.com/displayvideo/answer/9727714) and a list of
[advanced fields](https://support.google.com/displayvideo/answer/9748984) are available through the
[Display \& Video 360 Help Center](https://support.google.com/displayvideo/answer/9728993).

The following sections teach you how to add a new or updated script to a custom
bidding algorithm.

### Retrieve a script resource location

First, retrieve an available resource location under the custom bidding
algorithm resource with the
[`customBiddingAlgorithms.uploadScript`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms/uploadScript) method. This
request returns a [`CustomBiddingScriptRef`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts#CustomBiddingScriptRef) object with a
[resource name](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts#CustomBiddingScriptRef.FIELDS.resource_name). You can
[upload your script file](https://developers.google.com/display-video/api/v1beta2/guides/custom-bidding#upload_a_script_file) to the location dictated by the
resource name. Then use the custom bidding script reference object to
[create your script resource](https://developers.google.com/display-video/api/v1beta2/guides/custom-bidding#create_a_script_object).

Here's an example of how to retrieve an available resource
location:

### Python

```python
# Retrieve a usable custom bidding script reference
# object.
custom_bidding_script_ref = service.customBiddingAlgorithms().uploadScript(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

# Display the new custom bidding script reference object.
print('The following custom bidding script reference object was retrieved:'
      f'{custom_bidding_script_ref}')
```

### Upload a script file

After retrieving an available resource location, upload your script file to that
location in the Display \& Video 360 system with the
[`media.upload`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/media/upload) method. This method supports a
[simple upload](https://developers.google.com/display-video/api/guides/concepts/general/media-upload#simple-upload) that requires the query parameter
`uploadType=media`.

> [!WARNING]
> **Warning:** Custom bidding scripts have a maximum file size of 7MB.

Here's an example of how to upload a script file given a
retrieved custom bidding script reference object:

### Python

```python
# Create a media upload object.
media = MediaFileUpload(script-path)

# Create upload request.
upload_request = service.media().upload(
    resourceName=resource-name, media_body=media)

# Override response handler to expect null response.
upload_request.postproc = HttpRequest.null_postproc

# Upload script to resource location given in retrieved custom bidding
# script reference object.
upload_request.execute()
```

### Create a script object

Once the script file is uploaded, create a custom bidding script resource with
the [`customBiddingAlgorithms.scripts.create`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts/create) method. The
[`CustomBiddingScript`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts#CustomBiddingScript) object passed in the request should only
include the [`CustomBiddingScriptRef`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts#CustomBiddingScriptRef) object as the assigned
value of the [`script`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts#CustomBiddingScript.FIELDS.script) field. This associates the uploaded
script file with the new script resource.

> [!WARNING]
> **Warning:** If your uploaded script file has a syntax error, your [`customBiddingAlgorithms.scripts.create`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts/create) request will fail and return details on the syntax error found. To upload a fixed script file, you must restart this process by [retrieving a new script resource location](https://developers.google.com/display-video/api/v1beta2/guides/custom-bidding#retrieve_a_script_resource_location).

Here's an example of how to create a script file:

### Python

```python
# Create a custom bidding script object.
script_obj = {
    'script': custom-bidding-script-ref
}

# Create the custom bidding script.
response = service.customBiddingAlgorithms().scripts().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=script_obj).execute()

# Display the new custom bidding script object.
print(f'The following custom bidding script was created: {response}')
```

Once you create a custom bidding script resource, Display \& Video 360 processes the
script to make sure that it can be successfully used to score impressions.
Retrieve the state of this processing through the script object's
[`state`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms.scripts#CustomBiddingScript.FIELDS.state) field. Once the new script is accepted, the custom
bidding algorithm begins using the script to score impression values. This
happens immediately, so be sure that you want to update the algorithm before
creating a new script resource.

## Assign a Custom Bidding Algorithm

After you create a custom bidding algorithm, upload an accepted script, and meet
the [necessary requirements](https://support.google.com/displayvideo/answer/9723477), you can assign your custom
bidding algorithm to the bidding strategy of a line item or insertion order.

You can use custom bidding algorithms in
[maximize spend](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/BiddingStrategy#maximizespendbidstrategy) and
[performance goal](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/BiddingStrategy#performancegoalbidstrategy) bid strategies by assigning [`BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/BiddingStrategy#BiddingStrategyPerformanceGoalType.ENUM_VALUES.BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO)
and the [custom bidding algorithm ID](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/customBiddingAlgorithms#CustomBiddingAlgorithm.FIELDS.custom_bidding_algorithm_id) to the
[`performanceGoalType`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/BiddingStrategy#MaximizeSpendBidStrategy.FIELDS.performance_goal_type) and
[`customBiddingAlgorithmId`](https://developers.google.com/display-video/api/v1beta2/reference/rest/v1beta2/BiddingStrategy#MaximizeSpendBidStrategy.FIELDS.custom_bidding_algorithm_id) fields, respectively.
Depending on the bid strategy, other bid parameters may be available or
required.

Here's an example of how to update a line item to use a maximize
spend bid strategy with a given custom bidding algorithm:

### Python

```python
# Create the new bid strategy object.
bidding_strategy = {
    'maximizeSpendAutoBid': {
        'performanceGoalType':
            'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO',
        'customBiddingAlgorithmId': custom-bidding-algorithm-id
    }
}

# Create a line item object assigning the new bid strategy.
line_item_obj = {'bidStrategy': bidding_strategy}

# Update the line item with a new bid strategy.
response = service.advertisers().lineItems().patch(
    advertiserId=advertiser-id,
    lineItemId=line-item-id,
    updateMask='bidStrategy',
    body=line_item_obj).execute()

# Display the line item's new bid strategy
print(f'Line Item {response["name"]} is now using the following bid'
     f' strategy: {response["bidStrategy"]}.')
```