> ## Documentation Index > Fetch the complete documentation index at: https://docs.brandgate.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create or update customers > Up to 100 customers per request, matched by your external_id. To link a customer that already exists in BrandGate, send its id on the first sync. A customer is never merged by email: a clash is returned as customer_exists with existing_id. Assign a price list with price_list (its external_id). Fields you leave out are not changed. Requires the `customers:write` scope. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/customers openapi: 3.1.0 info: title: BrandGate API version: 1.0.0 description: >- Connect your ERP or software to BrandGate: read orders, products, customers and invoices; acknowledge orders and set their shipping status; create and update products, price lists and customers; set stock. Writes are batch upserts keyed by your own `external_id`, safe to repeat, and accept an `Idempotency-Key` header. Authenticate with an organization API key or an OAuth access token as `Authorization: Bearer `. servers: - url: https://api.brandgate.dev security: - apiKey: [] - oauth2: [] tags: - name: orders description: Orders placed by resellers. - name: products description: The product catalogue. - name: price_lists description: Customer price lists. - name: inventory description: Stock levels per SKU. - name: customers description: Resellers buying from the organization. - name: invoices description: Invoices sent to resellers. - name: webhook_endpoints description: Where BrandGate sends events. paths: /v1/customers: post: tags: - customers summary: Create or update customers description: >- Up to 100 customers per request, matched by your external_id. To link a customer that already exists in BrandGate, send its id on the first sync. A customer is never merged by email: a clash is returned as customer_exists with existing_id. Assign a price list with price_list (its external_id). Fields you leave out are not changed. Requires the `customers:write` scope. operationId: customersUpsert requestBody: required: true content: application/json: schema: type: object properties: items: type: array items: type: object properties: external_id: type: string minLength: 1 maxLength: 100 pattern: ^[\p{L}\p{N} ._\-/#:+]+$ id: type: string format: uuid customer_number: type: - string - 'null' maxLength: 50 company_name: type: string minLength: 1 maxLength: 200 contact_name: type: string minLength: 1 maxLength: 200 email: type: string format: email maxLength: 320 phone: type: - string - 'null' maxLength: 100 vat_number: type: - string - 'null' maxLength: 100 billing_address: type: object properties: line1: type: - string - 'null' maxLength: 500 city: type: - string - 'null' maxLength: 200 postal_code: type: - string - 'null' maxLength: 40 country: type: - string - 'null' maxLength: 100 additionalProperties: false shipping_address: type: object properties: line1: type: - string - 'null' maxLength: 500 city: type: - string - 'null' maxLength: 200 postal_code: type: - string - 'null' maxLength: 40 country: type: - string - 'null' maxLength: 100 additionalProperties: false payment_terms_days: type: - integer - 'null' minimum: 0 maximum: 365 preferred_currency: type: - string - 'null' pattern: ^[A-Z]{3}$ price_list: type: - string - 'null' minLength: 1 maxLength: 100 pattern: ^[\p{L}\p{N} ._\-/#:+]+$ status: type: string enum: - active - inactive source_updated_at: type: string format: date-time required: - external_id additionalProperties: false minItems: 1 maxItems: 100 required: - items additionalProperties: false responses: '200': description: Success. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: type: object properties: object: const: batch_result results: type: array items: type: object properties: external_id: type: string maxLength: 100 id: type: - string - 'null' format: uuid result: type: string enum: - created - updated - unchanged - error error: type: object properties: code: type: string enum: - stale_write - missing_field - sku_conflict - name_taken - customer_exists - unknown_product - unknown_price_list - invalid_value - plan_limit_reached message: type: string maxLength: 300 existing_id: type: string format: uuid required: - code - message additionalProperties: false required: - external_id - id - result additionalProperties: false counts: type: object properties: created: type: integer updated: type: integer unchanged: type: integer errors: type: integer required: - created - updated - unchanged - errors additionalProperties: false required: - object - results - counts additionalProperties: false '400': description: The request is invalid. `error.message` says which field. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, unknown, expired or revoked credentials. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The credentials lack the scope this operation needs. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Rate limited. Wait until `X-RateLimit-Reset` (or `Retry-After` seconds). content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] - oauth2: - customers:write components: headers: RequestId: description: Quote this when contacting support. schema: type: string format: uuid schemas: Error: type: object properties: error: type: object properties: code: type: string message: type: string request_id: type: string required: - code - message additionalProperties: false required: - error additionalProperties: false securitySchemes: apiKey: type: http scheme: bearer description: >- An organization API key (`bg_live_…`), created in BrandGate under Settings → API & MCP. oauth2: type: oauth2 description: >- For partner apps acting for many organizations. Authorization code with PKCE (S256). flows: authorizationCode: authorizationUrl: https://api.brandgate.dev/oauth/authorize tokenUrl: https://api.brandgate.dev/oauth/token refreshUrl: https://api.brandgate.dev/oauth/token scopes: orders:read: Read orders and their lines orders:write: Acknowledge orders and set their shipping status and tracking products:read: Read products and prices products:write: Create and update products and their base prices pricing:read: Read price lists pricing:write: Create and update price lists and their prices inventory:read: Read stock levels inventory:write: Update stock levels by SKU customers:read: Read customers (resellers), including contact details customers:write: Create and update customers and assign their price list invoices:read: Read invoices webhooks:read: List webhook endpoints webhooks:write: Create and delete webhook endpoints ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.