> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Update media billing entity (admin) > Update fields on an existing media billing entity. Setting `isPrimary: false` on the current primary is refused unless another entity is promoted in its place — an org always has exactly one primary once it has any entity. Admin-only. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml put /billing/media-entities/{entityId} openapi: 3.0.0 info: title: Scope3 Buyer API version: 2.0.0 description: |- REST API for advertisers to manage advertisers, campaigns, and reporting. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/buyer` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.interchange.io/api/v2/buyer description: Production server security: [] tags: - name: Signup description: Request reviewed access to Interchange - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Advertisers description: Manage advertisers - name: Product Discovery description: Discover and select products - name: Campaigns description: Manage advertising campaigns - name: Creatives description: Build, manage, and sync campaign creatives via AdCP Creative Protocol - name: Reporting description: Access performance metrics - name: Event Sources description: >- Manage event source configurations and log conversion/marketing events for attribution - name: Property Lists description: Validate property lists against AAO registry - name: Sales Agents description: View and connect sales agents - name: Measurement description: Measurement sources, records, context, and freshness - name: Syndication description: Syndicate resources to ADCP agents - name: Tasks description: Track async operation status - name: Buyer Billing description: >- Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer. - name: MCP description: Model Context Protocol endpoints for AI agents paths: /billing/media-entities/{entityId}: servers: - url: https://api.interchange.io/api/v2 description: Production server put: tags: - Media Billing summary: Update media billing entity (admin) description: >- Update fields on an existing media billing entity. Setting `isPrimary: false` on the current primary is refused unless another entity is promoted in its place — an org always has exactly one primary once it has any entity. Admin-only. operationId: updateMediaBillingEntity parameters: - in: path name: entityId schema: description: Surrogate id of the media billing entity. anyOf: - type: number - type: string required: true description: Surrogate id of the media billing entity. requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateMediaBillingEntityBody' responses: '200': description: Update media billing entity (admin) content: application/json: schema: $ref: '#/components/schemas/UpdateMediaBillingEntityResponse' '400': description: VALIDATION_ERROR (demoting the primary without a replacement). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: ACCESS_DENIED (not an account admin). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: NOT_FOUND (no such entity in this organization). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: CONFLICT (renaming onto an existing name/currency pair). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: UpdateMediaBillingEntityBody: type: object properties: entityName: type: string minLength: 1 maxLength: 255 description: >- Legal name of the media billing entity (e.g. "WPP South Africa (Pty) Ltd"). countryCode: type: string pattern: ^[A-Z]{2}$ description: >- Stored country identity metadata for the billing entity, as an ISO 3166-1 alpha-2 code. It does not derive currency, tax/address behavior, or resolution. example: US currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code example: USD billingEmails: minItems: 1 maxItems: 20 type: array items: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: >- Invoicing contact email(s) for this entity. At least one is required. addressLine1: type: string minLength: 1 maxLength: 255 description: Entity street address, line 1. addressLine2: description: Entity street address, line 2 (optional). type: string maxLength: 255 city: type: string minLength: 1 maxLength: 128 description: Entity city. state: description: Entity state/province/region (optional). type: string maxLength: 128 postalCode: type: string minLength: 1 maxLength: 32 description: Entity postal/ZIP code. taxId: description: >- Tax identifier for this entity (e.g. VAT number, EIN), when applicable. type: string maxLength: 64 isPrimary: description: >- Set true to promote this entity to PRIMARY (demoting any other primary entity in the same transaction), or false to demote it. Demoting the current primary is refused unless another entity is promoted in its place — an org always has exactly one primary once it has any entity. type: boolean description: Update fields on an existing media billing entity. UpdateMediaBillingEntityResponse: type: object properties: entity: $ref: '#/components/schemas/MediaBillingEntity' required: - entity additionalProperties: false ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response MediaBillingEntity: type: object properties: id: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Media billing entity ID entityName: type: string minLength: 1 maxLength: 255 description: >- Legal name of the media billing entity (e.g. "WPP South Africa (Pty) Ltd"). countryCode: type: string pattern: ^[A-Z]{2}$ description: >- Stored country identity metadata for the billing entity, as an ISO 3166-1 alpha-2 code. It does not derive currency, tax/address behavior, or resolution. example: US currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code example: USD billingEmails: minItems: 1 maxItems: 20 type: array items: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: >- Invoicing contact email(s) for this entity. At least one is required. addressLine1: type: string minLength: 1 maxLength: 255 description: Entity street address, line 1. addressLine2: nullable: true description: Entity street address, line 2 (optional). type: string maxLength: 255 city: type: string minLength: 1 maxLength: 128 description: Entity city. state: nullable: true description: Entity state/province/region (optional). type: string maxLength: 128 postalCode: type: string minLength: 1 maxLength: 32 description: Entity postal/ZIP code. taxId: nullable: true description: >- Tax identifier for this entity (e.g. VAT number, EIN), when applicable. type: string maxLength: 64 isPrimary: type: boolean description: >- Whether this is the org's PRIMARY media billing entity — the fallback in resolution previews when no advertiser or account attachment matches. At most one entity per org is primary; an org may have no entities at all. createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Creation timestamp (ISO 8601) updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Last update timestamp (ISO 8601) required: - id - entityName - countryCode - currency - billingEmails - addressLine1 - city - postalCode - isPrimary - createdAt - updatedAt additionalProperties: false description: >- A media billing configuration entity used by resolution previews. The invoice producer does not consume it yet. ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````