Prerequisites
- You need an API key with the
ad-product:readandad-product:writescopes. You can’t select these scopes in [Settings] > [Integrations] in the console. Ask Adrop, and we’ll issue you a key with both scopes. You can get the App API, Ad Unit API, and Audience Targeting API scopes on the same key. - The two scopes are checked separately. A key with only
ad-product:writegets403on read (GET) requests. Create, update, and restore responses include the full product, but you also needad-product:readto read products separately. - Get the ad unit IDs to put in a product with the Ad Unit API, or find them in the Ad Units menu in the console. Look up targeting IDs and targeting option IDs with the Audience Targeting API and the Context Targeting API.
Basics
When you get
429, wait for the number of seconds in the Retry-After header, then send the request again. When the server is busy, you can get 429 even if you send requests one at a time. For all request limits, see Limits.
Endpoints
Paths are relative to the Base URL.Create a Product
Creates an ad product.Request
ad-product:write scope. For the fields you can send, see Request Body.
Required Fields
Omitted fields get these defaults.
For an in-house product, you only need to send
title, pricing.pricingType: "INHOUSE", and unitGroups. The other values, such as private (private: true) and a unit price, product discount rate, and minimum budget of 0, are set automatically. If you send these fields, you can only send the values that are set automatically. Other values return 400.
Request Example
Response Example
Returns201 with the new product as a product object.
Create requests aren’t idempotent. If you resend a request because you didn’t get a response, the product can be created twice. Before resending, check the product list to see whether the product was created.
Errors
400: The request body doesn’t follow the product rules. See Error Handling.409 AD_PRODUCT_LIMIT_EXCEEDED: The project already has 1,000 products. Products scheduled for deletion count too.
Product Object
The get, create, update, and restore endpoints return products in this format. List products returns only part of it.discountRate,minBudget, andfrequencyaren’t filled with 0 when there’s no value. If a field has no value, don’t send it in updates either. Sending0forfrequencysets the product to no limit.- Product options you can only set in the console aren’t in the response. They stay as they are when you update the product with the API.
- In-house products are fixed to
private: true,0forprice,discountRate,minBudget, andmetric.eCTR, and9007199254740991formetric.eImpressions.
Request Body
Create and update request bodies can include these fields. Fields not listed here and fields that only appear in responses (_id, createdAt, updatedAt, deleteAt, unitGroups[].fixRequired, targetings[].kind) return 400 VALIDATION_FAILED.
Product Rules
Request bodies are checked against the product rules below. When a rule is broken, the API returns400 AD_PRODUCT_VALIDATION_FAILED and lists what’s wrong in detail.errors. An empty ad product name or an unknown billing type returns a request format error (400 VALIDATION_FAILED) instead.
Creative Sets
Each item inunitGroups is one creative set in the console. name is the creative set name shown to advertisers, and units is the list of ad unit IDs in the set.
- All units in a creative set must have the same format, size, and options (template, watermark, and so on). If a unit you add doesn’t match the set, the API returns
400 AD_UNIT_FIX_REQUIRED. For the criteria, see Configure Creative Sets. - Each unit ID can appear only once across all creative sets.
- Creative sets with the same format, size, and options can’t have the same name.
- A new creative set must contain at least one unit.
- The product must keep at least one unit that matches its creative set. Units that need modification don’t count.
fixRequired lists units whose format, size, or options changed after they were added, so they no longer match the creative set. This is the same as the Needs Modification status in the console. New campaigns can’t be booked on a product with these units (existing campaigns keep running), so revert the unit settings or remove the units from the creative set.
Changing the settings of a unit in a product or deleting the unit with the Ad Unit API also affects the product’s creative sets.
Targeting Policies
Each item intargetings is one targeting shown on the product. As in the console, use either audience targeting or context targeting in a product, not both.
policy takes the same choices as the console.
- Keys in
policiesmust be top-level option IDs of that targeting. For an option group, use the group’s ID, not the IDs of its sub-options. Other IDs return400 AD_PRODUCT_TARGETING_INVALID. - A product can have up to 500 include (
included) and exclude (excluded) policies. Optional (any) has no limit. - If a context targeting has include or exclude policies, you can’t add another context targeting with policies to the same product (
400 TARGETING_CONTEXT_EXCLUSIVE). - Adding the same targeting twice returns
400 TARGETING_DUPLICATED_IN_REQUEST. - Targeting IDs from other projects and IDs that don’t exist return
400 AD_PRODUCT_TARGETING_INVALID.
List Products
Returns the project’s products, newest first, one page at a time. Products scheduled for deletion are included withdeleteAt.
Request
ad-product:read scope.
Query Parameters
Request Example
Response Example
Returns200 with items (the products) and next (the cursor for the next page). If there’s no next, this is the last page.
targetingshas nopolicies. If you need the policies, get each product.unitGroupshasunitCount(number of units) andfixRequiredCount(number of units that need modification) instead of unit IDs.
next to read the following pages.
Get a Product
Returns one product with its targeting policies.Request
ad-product:read scope.
Request Example
Response
Returns200 with a product object.
policiescontains only policies for the targeting’s current top-level options. Policies for options that were deleted or moved into an option group aren’t in the response.- Products that use a context targeting with many options can have large responses. Get only the products you need.
Errors
404 AD_PRODUCT_NOT_FOUND: The product doesn’t exist or belongs to another project.
Update a Product
Changes only the fields you send.Request
ad-product:write scope. The request body is the same as the Request Body.
Query Parameters
How Updates Work
- Fields you don’t send stay as they are. An empty body
{}changes nothing. unitGroupsandtargetingsare replaced as whole arrays. Creative sets and targetings you don’t send are removed from the product.- In the
pricing,metric,options, andlocaleobjects, only the keys you send change. - If a
targetingsitem omitspolicies, that targeting’s policies stay as they are. If you sendpolicies, they’re replaced with the list you send, and policies for top-level options not in the list are removed. - Creative sets are matched to existing creative sets with the same name, and only newly added units are checked. You can send units that already needed modification as they are.
- When you change the billing type to
INHOUSE, the in-house values are set along with it. - You can’t clear the ad product name or remove all units from the product.
unitGroups and targetings, can overwrite changes made in the console in the meantime, so send ifUpdatedAt with them.
Request Example
Response
Returns200 with the updated product object.
Errors
404 AD_PRODUCT_NOT_FOUND: The product doesn’t exist or belongs to another project.409 AD_PRODUCT_CONFLICT:ifUpdatedAtdiffers from the product’supdatedAt. Get the product again, then update it.409 AD_PRODUCT_MUTATION_NOT_ACCEPTABLE: The product is scheduled for deletion. Restore it first.
Delete a Product
Schedules a product for deletion. Until the scheduled deletion time (deleteAt), you can restore the product.
Request
ad-product:write scope.
Request Example
Response Example
Returns200 with the product ID and the scheduled deletion time.
- If the latest end time among the product’s campaigns is later than now, the product is deleted 3 days after that end time. Otherwise, it’s deleted 3 days from now.
- Usually within a minute after the scheduled time passes, the product is deleted, and later requests for it return
404. - Products scheduled for deletion still appear in list and get responses with
deleteAt, and they count toward the project’s product limit. Deleting the product again recalculates the scheduled time.
Errors
404 AD_PRODUCT_NOT_FOUND: The product doesn’t exist or belongs to another project.
Restore a Product
Cancels a scheduled deletion and restores the product.Request
ad-product:write scope. Don’t send a request body.
Request Example
Response
Returns200 with the restored product object. Products that aren’t scheduled for deletion also return 200, and nothing changes.
Errors
404 AD_PRODUCT_NOT_FOUND: The product doesn’t exist, belongs to another project, or was already deleted.
Error Handling
Error Response
Error responses includestatusCode. Errors whose errorCode in the table below isn’t - also include errorCode. Errors that point to a problem in the request also include detail. Handle errors by errorCode, or by statusCode when there’s no errorCode.
detail.errors[], path is the location of the invalid field (such as pricing.price, unitGroups[0].name, or targetings[0].policies.<option ID>), and value is the value you sent. detail.errors holds up to 100 errors. After you fix them and resend, any remaining errors appear. Request format errors (VALIDATION_FAILED) also include the message and error fields.
Error Codes
Retrying
- For
429, wait for the time in theRetry-Afterheader, then resend. - If a write request (
POST,PATCH,DELETE, or restore) gets502or the connection drops without a response, the request may have been applied. Get the product to check before resending. Create requests aren’t idempotent, so resending one as is can create a duplicate product. - When you resend an update with
ifUpdatedAt, you can get409 AD_PRODUCT_CONFLICTif the earlier request was applied. Get the product again to check.