Skip to main content
The Ad Product API lets you create and manage ad products from your server. Use it to automate product creation you’d otherwise do in the console, or to keep Adrop ad products in sync with the products in your own sales system. The API works on the same data as ad products in the console. Products you create with the API appear in the console product list right away and are sold the same way as products created in the console. You can also read and update products created in the console.

Prerequisites

  • You need an API key with the ad-product:read and ad-product:write scopes. 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:write gets 403 on read (GET) requests. Create, update, and restore responses include the full product, but you also need ad-product:read to 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.
Call the API from your server only. Don’t put API keys in apps or web pages.

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

Requires the 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

Returns 201 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, and frequency aren’t filled with 0 when there’s no value. If a field has no value, don’t send it in updates either. Sending 0 for frequency sets 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, 0 for price, discountRate, minBudget, and metric.eCTR, and 9007199254740991 for metric.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 returns 400 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 in unitGroups 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 in targetings 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 policies must 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 return 400 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 with deleteAt.

Request

Requires the ad-product:read scope.

Query Parameters

Request Example

Response Example

Returns 200 with items (the products) and next (the cursor for the next page). If there’s no next, this is the last page.
List items differ from the product object in two ways.
  • targetings has no policies. If you need the policies, get each product.
  • unitGroups has unitCount (number of units) and fixRequiredCount (number of units that need modification) instead of unit IDs.
The order is mostly newest first, but older products may be out of order. Don’t rely on the order. Use next to read the following pages.

Get a Product

Returns one product with its targeting policies.

Request

Requires the ad-product:read scope.

Request Example

Response

Returns 200 with a product object.
  • policies contains 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

Requires the 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.
  • unitGroups and targetings are replaced as whole arrays. Creative sets and targetings you don’t send are removed from the product.
  • In the pricing, metric, options, and locale objects, only the keys you send change.
  • If a targetings item omits policies, that targeting’s policies stay as they are. If you send policies, 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.
If the same product is also changed in the console, the last save wins. Updates that replace whole arrays, such as unitGroups and targetings, can overwrite changes made in the console in the meantime, so send ifUpdatedAt with them.
If you take a get response, remove the response-only fields (_id, createdAt, updatedAt, deleteAt, unitGroups[].fixRequired, targetings[].kind, and the locale fields other than currency), and send the rest as is, nothing changes. To update safely, read the product, change only the values you need, and send it back.

Request Example

Response

Returns 200 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: ifUpdatedAt differs from the product’s updatedAt. 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

Requires the ad-product:write scope.

Request Example

Response Example

Returns 200 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

Requires the ad-product:write scope. Don’t send a request body.

Request Example

Response

Returns 200 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 include statusCode. 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.
In 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 the Retry-After header, then resend.
  • If a write request (POST, PATCH, DELETE, or restore) gets 502 or 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 get 409 AD_PRODUCT_CONFLICT if the earlier request was applied. Get the product again to check.

Limits