> ## Documentation Index > Fetch the complete documentation index at: https://docs.polinate.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a buyer (comprehensive CRUD) > Comprehensive buyer updates supporting: - Core buyer fields (name, legalName, primaryEmail, primaryPhone) - phantom buyers only - Partnership status updates (if supplier owns the partnership) - Create, update, and delete operations for emails, phones, and locations - Business buyers can only update partnership status (if owned) **Partnership Ownership:** Only the supplier that owns the partnership can update its status. Ownership is determined by which business created the partnership. **Phantom vs Business Buyers:** Phantom buyers (created via POST /buyers) support full CRUD operations. Business buyers (existing businesses) only support partnership status updates. ## OpenAPI ````yaml openapi.json patch /api/v1/buyers/{id} openapi: 3.0.3 info: title: Polinate External API version: 1.0.0 description: >- External API for partners and services. Authentication via X-Business-Id and X-API-Key headers. Credentials location: In the Polinate app, navigate to Business Settings → Integrations to find your Business ID and API Key. servers: - url: https://integrations.polinate.ai description: Production security: [] tags: - name: Items description: >- Manage items and item variants. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Buyers description: >- Create buyers and related contacts/locations. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Pricing description: >- Create price lists and entries. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Invoices description: >- List and update invoices. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). - name: Orders description: >- Order ingestion. Auth: X-Business-Id and X-API-Key (see Business Settings → Integrations). paths: /api/v1/buyers/{id}: patch: tags: - Buyers summary: Update a buyer (comprehensive CRUD) description: >- Comprehensive buyer updates supporting: - Core buyer fields (name, legalName, primaryEmail, primaryPhone) - phantom buyers only - Partnership status updates (if supplier owns the partnership) - Create, update, and delete operations for emails, phones, and locations - Business buyers can only update partnership status (if owned) **Partnership Ownership:** Only the supplier that owns the partnership can update its status. Ownership is determined by which business created the partnership. **Phantom vs Business Buyers:** Phantom buyers (created via POST /buyers) support full CRUD operations. Business buyers (existing businesses) only support partnership status updates. operationId: updateBuyer parameters: - schema: type: string example: phm_123 required: true name: id in: path - schema: type: string description: >- Business identifier for external auth. Find in Polinate app → Business Settings → Integrations. example: '{{businessId}}' required: true name: X-Business-Id in: header - schema: type: string description: >- Per-business API key for external auth. Find in Polinate app → Business Settings → Integrations. example: '{{apiKey}}' required: true name: X-API-Key in: header - schema: type: string description: Idempotency key for POST operations example: '{{idempotencyKey}}' required: false name: Idempotency-Key in: header requestBody: content: application/json: schema: $ref: '#/components/schemas/BuyerPatchRequest' examples: SimpleUpdate: summary: Update buyer core fields value: buyer: name: Updated Name Pty Ltd primaryEmail: newemail@example.com ContactCRUD: summary: Create, update, delete contacts value: createEmails: - email: newcontact@example.com contactName: New Contact isPrimary: false updatePhones: - id: phone_123 contactName: Updated Name isPrimary: true deleteLocations: - location_456 PartnershipStatus: summary: Update partnership status (requires ownership) value: partnershipStatus: SUSPENDED FullUpdate: summary: All operations at once value: buyer: name: Mega Corp partnershipStatus: ACTIVE createEmails: - email: orders@megacorp.com updatePhones: - id: phone_123 isPrimary: true deleteLocations: - old_location_id responses: '200': description: OK - Returns full updated buyer with all contacts content: application/json: schema: $ref: '#/components/schemas/BuyerDetailResponse' '400': description: Invalid payload or business buyer attempting non-status update content: application/json: schema: $ref: '#/components/schemas/StandardError' examples: ValidationError: summary: Invalid email format value: errorCode: VALIDATION_ERROR message: >- Some information looks incorrect. Please review the highlighted fields. fieldErrors: createEmails.0.email: Invalid email BusinessBuyerRestriction: summary: Business buyer cannot update contacts value: error: >- Business buyers do not support updating buyer fields or contacts. Only partnership status can be updated. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/StandardError' '403': description: Forbidden - No partnership or cannot update partnership status content: application/json: schema: $ref: '#/components/schemas/StandardError' examples: NoPartnership: summary: No active partnership value: error: You do not have an active partnership with this buyer NotOwner: summary: Cannot update partnership status value: error: >- You do not own this partnership and cannot update its status '404': description: Not Found - Buyer or contact resource not found content: application/json: schema: $ref: '#/components/schemas/StandardError' examples: BuyerNotFound: summary: Buyer does not exist value: error: Buyer not found EmailNotFound: summary: Email ID not found value: error: 'Email(s) not found: email_123' PhoneNotFound: summary: Phone ID not found value: error: 'Phone(s) not found: phone_123' LocationNotFound: summary: Location ID not found value: error: 'Location(s) not found: location_123' '429': description: Rate limited headers: Retry-After: schema: type: string description: Seconds to wait before retrying content: application/json: schema: $ref: '#/components/schemas/StandardError' components: schemas: BuyerPatchRequest: type: object properties: buyer: type: object properties: name: type: string legalName: type: string primaryEmail: type: string format: email primaryPhone: type: string additionalProperties: false partnershipStatus: type: string enum: - DECLINED - PENDING - REVIEW - ACTIVE - PAUSED - SUSPENDED - EXPIRED - TERMINATED createPhones: type: array items: type: object properties: phone: type: string description: Must be unique per buyer contactName: type: string isPrimary: type: boolean isVerified: type: boolean verifiedAt: type: string format: date-time sequence: type: number required: - phone updatePhones: type: array items: type: object properties: id: type: string phone: type: string contactName: type: string isPrimary: type: boolean isVerified: type: boolean verifiedAt: type: string format: date-time sequence: type: number required: - id deletePhones: type: array items: type: string createEmails: type: array items: type: object properties: email: type: string format: email description: Must be unique per buyer contactName: type: string isPrimary: type: boolean isVerified: type: boolean verifiedAt: type: string format: date-time sequence: type: number required: - email updateEmails: type: array items: type: object properties: id: type: string email: type: string format: email contactName: type: string isPrimary: type: boolean isVerified: type: boolean verifiedAt: type: string format: date-time sequence: type: number required: - id deleteEmails: type: array items: type: string createLocations: type: array items: type: object properties: label: type: string description: Must be unique per buyer type: type: string enum: - WAREHOUSE - DISTRIBUTION - STORE status: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED addressLine1: type: string addressLine2: type: string city: type: string state: type: string postcode: type: string country: type: string required: - label - type - status - addressLine1 - city - state - postcode - country updateLocations: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - WAREHOUSE - DISTRIBUTION - STORE status: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED addressLine1: type: string addressLine2: type: string city: type: string state: type: string postcode: type: string country: type: string required: - id deleteLocations: type: array items: type: string example: buyer: name: Updated Name Pty Ltd primaryEmail: newemail@example.com createEmails: - email: newcontact@example.com contactName: New Contact isPrimary: false deletePhones: - phone_id_to_delete partnershipStatus: ACTIVE BuyerDetailResponse: type: object properties: id: type: string name: type: string legalName: type: string primaryEmail: type: string nullable: true primaryPhone: type: string nullable: true status: type: string createdAt: type: string updatedAt: type: string deletedAt: type: string nullable: true properties: type: object properties: {} partnershipId: type: string partnershipStatus: type: string enum: - PENDING - ACTIVE - PAUSED - TERMINATED - DECLINED - EXPIRED itemListId: type: string nullable: true buyerInfo: type: object properties: {} emails: type: array items: type: object properties: id: type: string email: type: string format: email contactName: type: string nullable: true isPrimary: type: boolean isVerified: type: boolean verifiedAt: type: string nullable: true sequence: type: number nullable: true required: - id - email phones: type: array items: type: object properties: id: type: string phone: type: string contactName: type: string nullable: true isPrimary: type: boolean isVerified: type: boolean verifiedAt: type: string nullable: true sequence: type: number nullable: true required: - id - phone locations: type: array items: type: object properties: id: type: string label: type: string type: type: string status: type: string addressLine1: type: string addressLine2: type: string nullable: true city: type: string state: type: string postcode: type: string country: type: string required: - id - label required: - id - name - legalName - partnershipId - partnershipStatus - itemListId StandardError: type: object properties: errorCode: type: string message: type: string fieldErrors: type: object additionalProperties: type: string required: - errorCode - message ````