> ## Documentation Index
> Fetch the complete documentation index at: https://docs.targeter.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Update ad

> Change mutable fields on an existing ad

## Overview

Update an existing ad. Omitted fields stay unchanged. `campaign_id` and `office_id` cannot be changed after creation.

Targeter uses this for budget changes, flight date shifts, creative swaps, targeting edits, and platform mix updates.

Return **409** if the ad is `completed`, `rejected`, or otherwise not editable.

## Request

### Headers

* `Authorization: Bearer {token}` (required)
* `Content-Type: application/json`

### Path Parameters

<ParamField path="ad_id" type="string" required>
  Publisher-generated ad id returned from [Create ad](/integrations/ads/create)
</ParamField>

### Body Parameters

All fields are optional. Send only the fields that should change. Shapes match [Create ad](/integrations/ads/create).

<ParamField path="name" type="string">
  Ad name / title
</ParamField>

<ParamField path="budget" type="number">
  Updated spend cap
</ParamField>

<ParamField path="target_location" type="object">
  Updated geographic targeting
</ParamField>

<ParamField path="start_date" type="string">
  When the ad may start delivering (inclusive). UTC ISO 8601 date-time.
</ParamField>

<ParamField path="end_date" type="string">
  When the ad must stop delivering (inclusive). UTC ISO 8601 date-time.
</ParamField>

<ParamField path="goal_config" type="object">
  Updated objective and optimization event
</ParamField>

<ParamField path="publisher_platforms" type="string[]">
  Replacement list of platform ids (not a patch merge)
</ParamField>

<ParamField path="material" type="object">
  Replacement landing page and creatives. Include `target_url` plus at least one of `images`, `videos`, or `html5`.
</ParamField>

### Example Request

```bash theme={null}
curl -X PATCH "https://publisher.example.com/v1/ads/ad_9pL2wR" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "budget": 7500,
    "end_date": "2026-09-10T23:59:59Z"
  }'
```

## Response

### Success (200)

Returns the full ad after the update, including `ad_id` and current `status`.

```json theme={null}
{
    "ad_id": "ad_9pL2wR",
    "campaign_id": "AbC123xyz",
    "office_id": "off_8k2mQx",
    "name": "Majorstuenveien 14",
    "status": "active",
    "budget": 7500,
    "end_date": "2026-09-10T23:59:59Z"
}
```

## Error Responses

### 400 - Invalid request payload

```json theme={null}
{
    "error": "Invalid request payload",
    "details": [
        {
            "path": ["end_date"],
            "message": "end_date must be on or after start_date"
        }
    ]
}
```

### 401 - Unauthorized

```json theme={null}
{
    "error": "Missing or invalid Authorization header"
}
```

### 404 - Ad not found

```json theme={null}
{
    "error": "Ad not found"
}
```

### 409 - Ad cannot be updated

```json theme={null}
{
    "error": "Ad cannot be updated while status is completed"
}
```

### 500 - Server Error

```json theme={null}
{
    "error": "Unexpected server error. Please try again later."
}
```


## OpenAPI

````yaml integrations/openapi.json PATCH /ads/{ad_id}
openapi: 3.1.0
info:
  title: Targeter Ideal Publisher API
  description: >-
    Contract Targeter expects from publisher and media platforms it creates ads
    on and fetches insights from. Implement these endpoints so Targeter can
    manage offices, ads, and reporting against your system.
  version: 1.0.0
  contact:
    name: Targeter Integration Support
servers:
  - url: https://{publisher_host}/v1
    description: Publisher API host (provided during integration setup)
    variables:
      publisher_host:
        default: publisher.example.com
security:
  - BearerAuth: []
tags:
  - name: Offices
    description: Broker or advertiser offices that ads are billed and attributed to
  - name: Ads
    description: Create, update, pause, resume, and delete ads
  - name: Insights
    description: Performance reporting for ads Targeter has created
  - name: Platforms
    description: Publisher channels available for delivery
paths:
  /ads/{ad_id}:
    patch:
      tags:
        - Ads
      summary: Update ad
      description: >-
        Update mutable fields on an existing ad. Omitted fields are left
        unchanged. `campaign_id` and `office_id` are immutable after creation.
      operationId: updateAd
      parameters:
        - $ref: '#/components/parameters/AdId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAdRequest'
      responses:
        '200':
          description: Ad updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/AdNotFound'
        '409':
          description: Ad cannot be updated in its current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Ad cannot be updated while status is completed
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    AdId:
      name: ad_id
      in: path
      required: true
      description: Publisher-generated ad id returned from `POST /ads`
      schema:
        type: string
      example: ad_9pL2wR
  schemas:
    UpdateAdRequest:
      type: object
      description: Any subset of mutable ad fields. Omitted fields are unchanged.
      properties:
        name:
          type: string
          example: Majorstuenveien 14 — oppdatert
        budget:
          $ref: '#/components/schemas/Budget'
        target_location:
          $ref: '#/components/schemas/TargetLocation'
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        goal_config:
          $ref: '#/components/schemas/GoalConfig'
        publisher_platforms:
          type: array
          minItems: 1
          items:
            type: string
        material:
          $ref: '#/components/schemas/Material'
    Ad:
      type: object
      required:
        - ad_id
        - campaign_id
        - office_id
        - name
        - status
        - budget
        - target_location
        - start_date
        - end_date
        - goal_config
        - publisher_platforms
        - material
      properties:
        ad_id:
          type: string
          description: Publisher-generated ad id
          example: ad_9pL2wR
        campaign_id:
          type: string
          description: Targeter campaign id this ad belongs to
          example: AbC123xyz
        office_id:
          type: string
          description: Publisher office id from `POST /offices` or `GET /offices`
          example: off_8k2mQx
        name:
          type: string
          description: Ad name / title
          example: Majorstuenveien 14
        status:
          $ref: '#/components/schemas/AdStatus'
        budget:
          $ref: '#/components/schemas/Budget'
        target_location:
          $ref: '#/components/schemas/TargetLocation'
        start_date:
          type: string
          format: date-time
          description: When the ad may start delivering (inclusive)
          example: '2026-08-20T00:00:00Z'
        end_date:
          type: string
          format: date-time
          description: When the ad must stop delivering (inclusive)
          example: '2026-09-03T23:59:59Z'
        goal_config:
          $ref: '#/components/schemas/GoalConfig'
        publisher_platforms:
          type: array
          description: Platform ids from `GET /publisher-platforms`
          items:
            type: string
          example:
            - drammens_tidende
            - nettavisen
            - romerikes_blad
        material:
          $ref: '#/components/schemas/Material'
        created_at:
          type: string
          format: date-time
          example: '2026-08-19T08:12:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-08-19T08:12:00Z'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
          example: Missing required field
        details:
          type: array
          description: Per-field validation issues
          items:
            type: object
            required:
              - message
            properties:
              path:
                type: array
                items:
                  type: string
                example:
                  - material
                  - target_url
              message:
                type: string
                example: Target URL is required
    Budget:
      type: number
      description: Spend cap for the ad
      example: 5000
    TargetLocation:
      type: object
      required:
        - country
        - lat
        - long
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: 'NO'
        regions:
          type: array
          description: Region or county names
          items:
            type: string
          example:
            - Oslo
        lat:
          type: number
          description: Latitude of the targeting centre
          minimum: -90
          maximum: 90
          example: 59.9294
        long:
          type: number
          description: Longitude of the targeting centre
          minimum: -180
          maximum: 180
          example: 10.7166
        radius_km:
          type: number
          description: Optional radius in kilometres around `lat` and `long`
          example: 10
    GoalConfig:
      type: object
      required:
        - objective
      properties:
        objective:
          type: string
          description: Campaign objective Targeter is optimizing for
          enum:
            - traffic
            - conversions
            - awareness
            - leads
          example: traffic
        optimization_event:
          type: string
          description: Event to optimize delivery against
          enum:
            - impression
            - link_click
            - landing_page_view
            - lead
            - purchase
          example: link_click
    Material:
      type: object
      required:
        - target_url
      properties:
        target_url:
          type: string
          format: uri
          description: Landing page URL for the ad
          example: https://megler.no/eiendom/123
        images:
          type: array
          description: Publicly reachable image URLs
          items:
            type: string
            format: uri
          example:
            - https://example.com/property-photo.jpg
        videos:
          type: array
          description: Publicly reachable video URLs
          items:
            type: string
            format: uri
            example: https://example.com/property-tour.mp4
          example:
            - https://example.com/property-tour.mp4
        html5:
          type: array
          description: Publicly reachable HTML5 creative URLs
          items:
            type: string
            format: uri
            example: https://example.com/creatives/majorstuenveien-14.html
          example:
            - https://example.com/creatives/majorstuenveien-14.html
    AdStatus:
      type: string
      description: Delivery status of the ad
      enum:
        - draft
        - pending_review
        - scheduled
        - active
        - paused
        - completed
        - rejected
        - error
      example: active
  responses:
    BadRequest:
      description: Invalid request payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid request payload
            details:
              - path:
                  - name
                message: 'Invalid input: expected string, received undefined'
    Unauthorized:
      description: Missing Authorization header, or invalid or expired token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingHeader:
              value:
                error: Missing or invalid Authorization header
            invalidToken:
              value:
                error: Invalid or expired token
    AdNotFound:
      description: Ad not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Ad not found
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unexpected server error. Please try again later.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token issued to Targeter during integration setup. Send as
        `Authorization: Bearer <token>`.

````