> ## Documentation Index > Fetch the complete documentation index at: https://docs.interchange.io/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: Account description: Account management, service tokens, and preferences - 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: Planning Briefs description: >- Share prospective briefs with publishers and collect their fit/quote/clarify/decline/book responses (gated by the demand-supply-signals flag). - 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: type: object properties: entityName: description: >- Legal name of the media billing entity (e.g. "WPP South Africa (Pty) Ltd"). type: string minLength: 1 maxLength: 255 countryCode: description: >- Country of the billing entity, as an ISO 3166-1 alpha-2 code. Metadata only — drives tax treatment and bank/address formatting, never invoice routing (money-streams.md §6.4). example: US type: string pattern: ^[A-Z]{2}$ currency: description: ISO 4217 currency code example: USD type: string pattern: ^[A-Z]{3}$ billingEmails: description: >- Invoicing contact email(s) for this entity. At least one is required. 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,}$ addressLine1: description: Entity street address, line 1. type: string minLength: 1 maxLength: 255 addressLine2: description: Entity street address, line 2 (optional). type: string maxLength: 255 city: description: Entity city. type: string minLength: 1 maxLength: 128 state: description: Entity state/province/region (optional). type: string maxLength: 128 postalCode: description: Entity postal/ZIP code. type: string minLength: 1 maxLength: 32 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 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: UpdateMediaBillingEntityResponse: type: object properties: entity: $ref: '#/components/schemas/MediaBillingEntity' required: - entity additionalProperties: false ErrorResponse: description: Standard error response type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false MediaBillingEntity: description: A media billing entity — a legal entity Scope3 invoices for media spend. type: object properties: id: description: Media billing entity ID type: integer minimum: -9007199254740991 maximum: 9007199254740991 entityName: description: >- Legal name of the media billing entity (e.g. "WPP South Africa (Pty) Ltd"). type: string minLength: 1 maxLength: 255 countryCode: description: >- Country of the billing entity, as an ISO 3166-1 alpha-2 code. Metadata only — drives tax treatment and bank/address formatting, never invoice routing (money-streams.md §6.4). example: US type: string pattern: ^[A-Z]{2}$ currency: description: ISO 4217 currency code example: USD type: string pattern: ^[A-Z]{3}$ billingEmails: description: >- Invoicing contact email(s) for this entity. At least one is required. 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,}$ addressLine1: description: Entity street address, line 1. type: string minLength: 1 maxLength: 255 addressLine2: nullable: true description: Entity street address, line 2 (optional). type: string maxLength: 255 city: description: Entity city. type: string minLength: 1 maxLength: 128 state: nullable: true description: Entity state/province/region (optional). type: string maxLength: 128 postalCode: description: Entity postal/ZIP code. type: string minLength: 1 maxLength: 32 taxId: nullable: true description: >- Tax identifier for this entity (e.g. VAT number, EIN), when applicable. type: string maxLength: 64 isPrimary: description: >- Whether this is the org's PRIMARY media billing entity — the mandatory backstop used when no advertiser or account attachment matches. At most one entity per org is primary. type: boolean createdAt: description: Creation timestamp (ISO 8601) 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))$ updatedAt: description: Last update timestamp (ISO 8601) 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))$ required: - id - entityName - countryCode - currency - billingEmails - addressLine1 - city - postalCode - isPrimary - createdAt - updatedAt additionalProperties: false ApiError: description: Structured error object type: object properties: code: description: Machine-readable error code type: string message: description: Human-readable error message type: string field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````