--- updatedAt: 2026-09-24T22:59:05.000Z agentTools: projectIndex: https://developers.getbyrd.com/llms.txt --- # Update your account details Changes only the fields you send; read-only fields cannot be changed. A customer account must keep a phone number. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "description": "The byrd APIs for managing products, inbound deliveries, shipments and returns.", "contact": { "email": "info@getbyrd.com", "name": "General company contact", "url": "https://getbyrd.com/kontakt/" }, "license": { "name": "Copyright byrd technologies GmbH" }, "termsOfService": "https://getbyrd.com/agb/", "version": "20260924", "title": "byrd APIs" }, "servers": [ { "description": "Production server", "url": "https://api.getbyrd.com/" } ], "security": [ { "tokenAuth": [] } ], "paths": { "/v2/users/{user_id}": { "patch": { "operationId": "userapiv2_patch", "responses": { "200": { "content": { "application/vnd.byrd.customer+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/User" } } } } }, "description": "Success response to a valid request" }, "400": { "$ref": "#/components/responses/Error", "description": "The request set `status` on a user who is not a customer. Only customer accounts carry one.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "User.Update.Invalid.Status" ] } } } } } }, "401": { "description": "The request changed a field the caller's role may not write - `isStaff`, `v3CarrierSelector` or `status`. The offending field is named in `extra.field`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "User.Update.Permission.Insufficient" ] } } } } } }, "403": { "$ref": "#/components/responses/Error" }, "422": { "description": "The request mentioned `isDemo`, which is set when the account is created and cannot be changed afterwards.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "User.Update.Immutable.IsDemo" ] } } } } } } }, "tags": [ "Authentication" ], "description": "Changes only the fields you send; read-only fields cannot be changed.\nA customer account must keep a phone number.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } } }, "x-byrd-roles": [ "sales", "admin", "warehouse", "scoped_admin", "customer", "operator", "customer_support", "warehouse_support", "service" ], "x-byrd-permissions": { "type": "permission", "name": "user:write" }, "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of your byrd account (UUID); any other account answers `404`." } ], "summary": "Update your account details" } } }, "components": { "securitySchemes": { "tokenAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Authorization with previously obtained JSON Web Token" } }, "responses": { "Error": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Generic error response" } }, "schemas": { "Address": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the record (UUID)." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was last changed (ISO 8601)." }, "thoroughfare": { "type": "string", "description": "Street name; send the house number in `subThoroughfare` where possible.", "nullable": true }, "subThoroughfare": { "type": "string", "description": "House or building number.", "nullable": true }, "subSubThoroughfare": { "type": "string", "description": "Additional address details, such as building, floor or apartment.", "nullable": true }, "locality": { "type": "string", "description": "City or town." }, "subLocality": { "type": "string", "description": "District or neighbourhood within the city.", "nullable": true }, "adminArea": { "type": "string", "description": "State, province or region, where the country uses one.", "nullable": true }, "subAdminArea": { "type": "string", "description": "County or district below the state or region.", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code. A prefix matching `countryCode`, as in `DE-12345`, is removed." }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country, as an ISO 3166-1 alpha-2 code." }, "latitude": { "type": "number", "description": "Latitude of the address, in decimal degrees.", "nullable": true }, "longitude": { "type": "number", "description": "Longitude of the address, in decimal degrees.", "nullable": true }, "validated": { "type": "boolean", "readOnly": true, "description": "Whether byrd has validated the address. `false` only means it was not validated, not that it is invalid." } }, "required": [ "countryCode", "locality", "postalCode" ], "title": "Address" }, "Error": { "type": "object", "required": [ "code", "message", "errors" ], "properties": { "code": { "type": "string", "enum": [ "Authentication.AuthenticationRequired", "Authentication.ExpiredJWTToken", "Authentication.InvalidCredentials", "Authentication.InvalidJWTToken", "Authentication.LocalityRequired", "Authentication.MissingPermission", "Authentication.ReadOnly", "Authentication.RoleNotAllowed", "Authentication.UserLocked", "Exception.404", "Exception.500", "Request.InvalidPagination", "Request.InvalidQuery", "Request.InvalidSchema", "Request.NoInput", "Request.ResourceNotFound" ] }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "description": "Embedded instance of Error" } } }, "title": "Error" }, "TotalPrice": { "type": "object", "properties": { "value": { "type": "number", "description": "Amount, as a string with two decimals separated by a dot." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency (ISO 4217 code, e.g. `EUR`)." }, "taxFactor": { "type": "number", "description": "Tax factor of the price, for example `1.19` for 19% VAT; `null` when not set.", "nullable": true } }, "required": [ "currency", "value" ], "title": "Total price" }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the record (UUID)." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was last changed (ISO 8601)." }, "firstName": { "type": "string", "description": "First name of the account holder." }, "lastName": { "type": "string", "description": "Last name of the account holder." }, "companyName": { "type": "string", "description": "Name of your company; `null` when not set.", "nullable": true }, "senderName": { "type": "string", "description": "Sender name printed on shipping labels instead of the company name; `null` when not set.", "nullable": true }, "vatNumber": { "type": "string", "description": "VAT number of your company; `null` when not set.", "nullable": true }, "eoriNumber": { "type": "string", "description": "EORI number of your company, used on export customs documents; `null` when not set.", "nullable": true }, "phone": { "type": "string", "pattern": "^[0-9+()/ -]*$", "description": "Phone number of your company: digits, spaces and `+ ( ) / -` only. Required: it may be printed on shipping labels.", "nullable": true }, "email": { "type": "string", "format": "email", "description": "Email address you log in to the dashboard with." }, "billingEmail": { "type": "string", "format": "email", "description": "Email address invoices are sent to; `null` when not set.", "nullable": true }, "sendTrackingEmails": { "type": "boolean", "description": "Whether byrd sends the recipients of your shipments a tracking email after the shipment is sent." }, "billingAddress": { "description": "Billing address of your company.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "codIBAN": { "type": "string", "description": "IBAN of the bank account cash-on-delivery amounts are paid out to; `null` when not set.", "nullable": true }, "codBIC": { "type": "string", "description": "BIC of the bank account cash-on-delivery amounts are paid out to; `null` when not set.", "nullable": true }, "userDefaults": { "type": "object", "description": "Free-form JSON object with your dashboard preferences. An update replaces the whole object.", "additionalProperties": {} }, "language": { "type": "string", "enum": [ "en", "de", "pl", "fr", "it", "es", null ], "description": "Preferred language of the dashboard; `null` when not set.\n\n- `en`: English\n- `de`: German\n- `pl`: Polish\n- `fr`: French\n- `it`: Italian\n- `es`: Spanish", "nullable": true }, "addressValidationEnabled": { "type": "boolean", "description": "Whether byrd validates the destination address of your shipments before releasing them. Pickup shipments are never validated." }, "economyFallbackEnabled": { "type": "boolean", "description": "Whether an `economy` shipment is sent with `standard` shipping when no economy service is available for it. Does not apply to B2B shipments." }, "defaultShipmentService": { "type": "string", "enum": [ "economy", "standard", "express" ], "description": "Shipping service applied to shipments you create without naming one. B2B and pallet shipments always start with `standard`. Defaults to `standard`.\n\n- `economy`: cheapest, slower delivery\n- `standard`: regular delivery\n- `express`: faster delivery, picked with higher priority" }, "partialFulfillmentEnabled": { "type": "boolean", "description": "Whether byrd tries to split a shipment when one or more of its SKUs are out of stock." }, "b2bPalletEnabled": { "type": "boolean", "description": "Whether you can create B2B shipments sent on pallets." }, "fallbackPhoneEnabled": { "type": "boolean", "description": "Whether your phone number is used on shipping labels when the recipient has no phone number. Defaults to `true`." }, "blockedShipmentRetryEnabled": { "type": "boolean", "description": "Whether shipments that could not be released for lack of stock are released again automatically, oldest first, once the stock is replenished. Defaults to `false`." }, "ioss": { "type": "string", "description": "Import One-Stop Shop (IOSS) number used for customs declarations; `null` when not set. Set it to `null` to stop it being sent.", "nullable": true }, "ukims": { "type": "string", "description": "UK Internal Market Scheme (UKIMS) number used for customs declarations; `null` when not set. Set it to `null` to stop it being sent.", "nullable": true }, "countryCode": { "type": "string", "readOnly": true, "description": "Country your account is registered in, as a two-letter code (ISO 3166-1 alpha-2, except `EL` for Greece)." }, "fulfillmentProviderKey": { "type": "string", "readOnly": true, "description": "Key of the fulfillment provider your account belongs to." }, "referralPromotionCode": { "type": "string", "readOnly": true }, "warehousingEnabled": { "type": "boolean", "readOnly": true, "description": "Whether warehousing is enabled for your account. Deprecated." }, "enabledServices": { "type": "object", "readOnly": true, "description": "byrd applications the user can access, as an object of booleans: `customers` (the customer dashboard), `partners` (the warehouse dashboard) and `warehousing` (deprecated).", "additionalProperties": {} }, "directComplete": { "type": "boolean", "readOnly": true, "description": "Whether the warehouse may use the simplified picking process for your shipments, skipping barcode scans when picking." }, "brandingEnabled": { "type": "boolean", "readOnly": true, "description": "Whether the warehouse adds your branding items to all your shipments." }, "localities": { "readOnly": true, "description": "Warehouses your account is linked to.", "type": "array", "items": { "$ref": "#/components/schemas/UserLocality" }, "nullable": true }, "notificationConfig": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether the daily report email is sent to you." }, "lastSent": { "type": "string", "format": "date", "readOnly": true, "description": "Date the daily report was last sent (ISO 8601); `null` when it was never sent." }, "sendHour": { "type": "integer", "minimum": 5, "maximum": 21, "description": "Hour of the day, in `timezone`, at which the daily report is sent. Leave unset to keep the default of 09:00 Europe/Vienna.", "nullable": true }, "timezone": { "type": "string", "description": "IANA timezone name `sendHour` is read in, e.g. `Europe/Vienna`.", "nullable": true } }, "description": "Settings of the daily report email; `null` when never configured.", "nullable": true }, "inventoryInsurance": { "type": "boolean", "readOnly": true, "description": "Whether you have booked inventory insurance with byrd." }, "euleEnabled": { "type": "boolean", "readOnly": true, "description": "Whether you may use the byrdAI MCP server, for example in Claude or ChatGPT." }, "returnsPortalTabVisible": { "type": "boolean", "readOnly": true, "description": "Whether the Returns tab is shown in your dashboard profile." }, "returnsPortalEnabled": { "type": "boolean", "readOnly": true, "description": "Whether you may configure your returns portal in the dashboard. The returns portal is an add-on; contact byrd to enable it." }, "shippingLabelName": { "type": "string", "readOnly": true, "description": "Sender name printed on your shipping labels: `senderName` if set, else `companyName`, else your first and last name." }, "invoiceAllowed": { "type": "boolean", "readOnly": true, "description": "Whether you may pay by bank transfer against invoice instead of by credit card or SEPA direct debit." }, "credit": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/TotalPrice" } ] }, "passwordRequiresChange": { "type": "boolean", "readOnly": true, "description": "Whether you must change your password at the next login." }, "warehouseInstructions": { "type": "string", "readOnly": true, "description": "Packing instructions the warehouse follows for all your shipments (HTML); `null` when there are none.", "nullable": true }, "skipBarcodePick": { "type": "boolean", "readOnly": true, "description": "Whether warehouse staff may skip scanning product barcodes when picking and packing your shipments." }, "isStaff": { "type": "boolean", "readOnly": true, "description": "Whether the account belongs to a byrd employee." }, "unpaidBalance": { "type": "boolean", "readOnly": true, "description": "Whether your account has an unpaid balance." }, "fulfillmentLock": { "type": "boolean", "readOnly": true, "description": "Whether fulfillment of your shipments is stopped. While `true`, new and existing shipments are not released to the warehouse." }, "role": { "type": "string", "enum": [ "sales", "admin", "warehouse", "scoped_admin", "courier", "customer", "monitor", "operator", "customer_support", "warehouse_support", "service", "local_admin", null ], "readOnly": true, "description": "Role of the user; `customer` for customer accounts.", "nullable": true } }, "required": [ "email", "firstName", "lastName", "role", "sendTrackingEmails", "warehouseInstructions" ], "title": "User" }, "UserLocality": { "type": "object", "properties": { "localityID": { "type": "string", "description": "ID of the warehouse (UUID)." } }, "title": "User locality" }, "UserUpdate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "readOnly": true, "description": "ID of the record (UUID)." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the record was last changed (ISO 8601)." }, "firstName": { "type": "string", "description": "First name of the account holder." }, "lastName": { "type": "string", "description": "Last name of the account holder." }, "companyName": { "type": "string", "description": "Name of your company; `null` when not set.", "nullable": true }, "senderName": { "type": "string", "description": "Sender name printed on shipping labels instead of the company name; `null` when not set.", "nullable": true }, "vatNumber": { "type": "string", "description": "VAT number of your company; `null` when not set.", "nullable": true }, "eoriNumber": { "type": "string", "description": "EORI number of your company, used on export customs documents; `null` when not set.", "nullable": true }, "phone": { "type": "string", "pattern": "^[0-9+()/ -]*$", "description": "Phone number of your company: digits, spaces and `+ ( ) / -` only. Required: it may be printed on shipping labels.", "nullable": true }, "email": { "type": "string", "format": "email", "description": "Email address you log in to the dashboard with." }, "billingEmail": { "type": "string", "format": "email", "description": "Email address invoices are sent to; `null` when not set.", "nullable": true }, "sendTrackingEmails": { "type": "boolean", "description": "Whether byrd sends the recipients of your shipments a tracking email after the shipment is sent." }, "billingAddress": { "readOnly": false, "description": "Billing address of your company. Send the complete address: it replaces the stored one rather than being merged into it.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "codIBAN": { "type": "string", "description": "IBAN of the bank account cash-on-delivery amounts are paid out to; `null` when not set.", "nullable": true }, "codBIC": { "type": "string", "description": "BIC of the bank account cash-on-delivery amounts are paid out to; `null` when not set.", "nullable": true }, "userDefaults": { "type": "object", "description": "Free-form JSON object with your dashboard preferences. An update replaces the whole object.", "additionalProperties": {} }, "language": { "type": "string", "enum": [ "en", "de", "pl", "fr", "it", "es", null ], "description": "Preferred language of the dashboard; `null` when not set.\n\n- `en`: English\n- `de`: German\n- `pl`: Polish\n- `fr`: French\n- `it`: Italian\n- `es`: Spanish", "nullable": true }, "addressValidationEnabled": { "type": "boolean", "description": "Whether byrd validates the destination address of your shipments before releasing them. Pickup shipments are never validated." }, "economyFallbackEnabled": { "type": "boolean", "description": "Whether an `economy` shipment is sent with `standard` shipping when no economy service is available for it. Does not apply to B2B shipments." }, "defaultShipmentService": { "type": "string", "enum": [ "economy", "standard", "express" ], "description": "Shipping service applied to shipments you create without naming one. B2B and pallet shipments always start with `standard`. Defaults to `standard`.\n\n- `economy`: cheapest, slower delivery\n- `standard`: regular delivery\n- `express`: faster delivery, picked with higher priority" }, "partialFulfillmentEnabled": { "type": "boolean", "description": "Whether byrd tries to split a shipment when one or more of its SKUs are out of stock." }, "b2bPalletEnabled": { "type": "boolean", "description": "Whether you can create B2B shipments sent on pallets." }, "fallbackPhoneEnabled": { "type": "boolean", "description": "Whether your phone number is used on shipping labels when the recipient has no phone number. Defaults to `true`." }, "blockedShipmentRetryEnabled": { "type": "boolean", "description": "Whether shipments that could not be released for lack of stock are released again automatically, oldest first, once the stock is replenished. Defaults to `false`." }, "ioss": { "type": "string", "description": "Import One-Stop Shop (IOSS) number used for customs declarations; `null` when not set. Set it to `null` to stop it being sent.", "nullable": true }, "ukims": { "type": "string", "description": "UK Internal Market Scheme (UKIMS) number used for customs declarations; `null` when not set. Set it to `null` to stop it being sent.", "nullable": true }, "countryCode": { "type": "string", "readOnly": true, "description": "Country your account is registered in, as a two-letter code (ISO 3166-1 alpha-2, except `EL` for Greece)." }, "fulfillmentProviderKey": { "type": "string", "readOnly": true, "description": "Key of the fulfillment provider your account belongs to." }, "referralPromotionCode": { "type": "string", "readOnly": true }, "warehousingEnabled": { "type": "boolean", "readOnly": true, "description": "Whether warehousing is enabled for your account. Deprecated." }, "enabledServices": { "type": "object", "readOnly": true, "description": "byrd applications the user can access, as an object of booleans: `customers` (the customer dashboard), `partners` (the warehouse dashboard) and `warehousing` (deprecated).", "additionalProperties": {} }, "directComplete": { "type": "boolean", "readOnly": true, "description": "Whether the warehouse may use the simplified picking process for your shipments, skipping barcode scans when picking." }, "brandingEnabled": { "type": "boolean", "readOnly": true, "description": "Whether the warehouse adds your branding items to all your shipments." }, "localities": { "readOnly": true, "description": "Warehouses your account is linked to.", "type": "array", "items": { "$ref": "#/components/schemas/UserLocality" }, "nullable": true }, "notificationConfig": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether the daily report email is sent to you." }, "lastSent": { "type": "string", "format": "date", "readOnly": true, "description": "Date the daily report was last sent (ISO 8601); `null` when it was never sent." }, "sendHour": { "type": "integer", "minimum": 5, "maximum": 21, "description": "Hour of the day, in `timezone`, at which the daily report is sent. Leave unset to keep the default of 09:00 Europe/Vienna.", "nullable": true }, "timezone": { "type": "string", "description": "IANA timezone name `sendHour` is read in, e.g. `Europe/Vienna`.", "nullable": true } }, "description": "Settings of the daily report email; `null` when never configured.", "nullable": true }, "inventoryInsurance": { "type": "boolean", "readOnly": true, "description": "Whether you have booked inventory insurance with byrd." }, "euleEnabled": { "type": "boolean", "readOnly": true, "description": "Whether you may use the byrdAI MCP server, for example in Claude or ChatGPT." }, "returnsPortalTabVisible": { "type": "boolean", "readOnly": true, "description": "Whether the Returns tab is shown in your dashboard profile." }, "returnsPortalEnabled": { "type": "boolean", "readOnly": true, "description": "Whether you may configure your returns portal in the dashboard. The returns portal is an add-on; contact byrd to enable it." }, "shippingLabelName": { "type": "string", "readOnly": true, "description": "Sender name printed on your shipping labels: `senderName` if set, else `companyName`, else your first and last name." }, "invoiceAllowed": { "type": "boolean", "readOnly": true, "description": "Whether you may pay by bank transfer against invoice instead of by credit card or SEPA direct debit." }, "credit": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/TotalPrice" } ] }, "passwordRequiresChange": { "type": "boolean", "readOnly": true, "description": "Whether you must change your password at the next login." }, "warehouseInstructions": { "type": "string", "readOnly": true, "description": "Packing instructions the warehouse follows for all your shipments (HTML); `null` when there are none.", "nullable": true }, "skipBarcodePick": { "type": "boolean", "readOnly": true, "description": "Whether warehouse staff may skip scanning product barcodes when picking and packing your shipments." }, "isStaff": { "type": "boolean", "readOnly": true, "description": "Whether the account belongs to a byrd employee." }, "unpaidBalance": { "type": "boolean", "readOnly": true, "description": "Whether your account has an unpaid balance." }, "fulfillmentLock": { "type": "boolean", "readOnly": true, "description": "Whether fulfillment of your shipments is stopped. While `true`, new and existing shipments are not released to the warehouse." }, "role": { "type": "string", "enum": [ "sales", "admin", "warehouse", "scoped_admin", "courier", "customer", "monitor", "operator", "customer_support", "warehouse_support", "service", "local_admin", null ], "readOnly": true, "description": "Role of the user; `customer` for customer accounts.", "nullable": true } }, "required": [ "email", "firstName", "lastName", "role", "sendTrackingEmails", "warehouseInstructions" ], "title": "User update" } } }, "tags": [ { "name": "Authentication", "description": "Log in with your API key to get an access token, refresh it, and read or update your account." } ], "x-readme": { "apply-tag-changes": true, "apply-endpoint-order": true } } ```