--- updatedAt: 2026-09-11T16:27:57.000Z agentTools: projectIndex: https://docs.shuttleglobal.com/llms.txt --- # Update an account Update an existing account's details. When using a CRM key in the path, this endpoint will update the first account that was created with that CRM key. Note: Multiple accounts can share the same CRM key, but operations using the CRM key in the path will always target the first account created with that key. ## Business Rules The logic behind this operation: * [Update an account](/docs/ug-rules-account-update) # OpenAPI definition ````json { "openapi": "3.0.0", "info": { "title": "Shuttle API", "description": "Complete API specification for the Shuttle platform.\n\n# List APIs\nList APIs allow you to pass search criteria, order clauses, and expansion parameters.\n\n## Criteria\nThe `criteria` parameter allows filtering results based on specific conditions:\n\nSupports operators:\n- `!=`, `>=`, `>`, `<`, `<=`: Standard comparison operators\n- `=`: Exact match, separate multiple values with `;` for IN operation\n- `~=`: Partial match (case insensitive)\n- `<>`: Between, separate values with `;` (e.g., `<>min;max`)\n- `!`: Is null\n- `!!`: Is not null\n\nSeparate multiple criteria with commas (`,`)\n\nNotes:\n- Strings are case insensitive (some exceptions apply)\n- Booleans are Y/N (TIP: we recommend checking for `=Y` or `!=Y` as some objects treat false as null)\n\nExamples:\n```\ncriteria=status=ACTIVE;FAILING\ncriteria=status=ACTIVE;FAILING,email=dave@gmail.com\ncriteria=scheduler=Y\n```\n\nRemember to URL encode the criteria parameter.\n\n## Order\nThe `order` parameter controls the sort order of results:\n\n- Supports any field that criteria supports\n- Defaults to `created:desc` if not specified\n- Will order ascending unless you specify `desc`\n- Separate multiple order fields with commas (`,`)\n\nExamples:\n```\norder=updated\norder=updated:desc\norder=status,updated:desc\n```\n\n## Expansion\nThe `expand` parameter allows you to include related objects in the response:\n\n- Specify fields to expand, separated by commas\n- Some objects support nested expansion using dot notation\n- Expanded objects are included in the response under their respective fields\n\nExample:\n```\nexpand=customer,payment_method\nexpand=customer.addresses,payment_method.card\n```\n\n# Authentication\nAll API requests must be authenticated using one of these methods:\n\n## 1. Basic Authentication\nUse your secret key as credentials:\n```\nAuthorization: Basic Base64(secret_key:)\n```\n- Required: Include your instance ID in the URL path\n- Example: `https://app.shuttleglobal.com/c/api/instances/inst_123/payment_links`\n\n## 2. Bearer Token Authentication\nUse an OAuth access token:\n```\nAuthorization: Bearer \n```\n- Optional: Instance ID in URL (token identifies your instance)\n- Example: `https://app.shuttleglobal.com/c/api/payment_links`\n- Get tokens from the OAuth /token endpoint\n- Only tokens issued for your instance will work\n", "license": { "name": "Proprietary", "url": "https://shuttleglobal.com/terms" }, "version": "1.0.0" }, "tags": [ { "name": "charges", "description": "API for managing payment charges in the Shuttle platform." }, { "name": "accounts", "description": "API for managing accounts in the Shuttle platform." } ], "servers": [ { "url": "https://app.shuttleglobal.com/c/api/instances/{instance_key}", "description": "Production server with API Key Authentication", "variables": { "instance_key": { "description": "Your instance ID (required for Basic auth)", "default": "default" } } }, { "url": "https://app.shuttleglobal.com/c/api", "description": "Production server with Bearer Token Authentication" } ], "security": [ { "basicAuth": [] }, { "bearerAuth": [] } ], "paths": { "/charges": { "get": { "summary": "List charges", "operationId": "listCharges", "tags": [ "charges" ], "description": "Search and filter charge objects with pagination support.\n\nAvailable fields for criteria and order:\n- id\n- alt_key\n- contract\n- created\n- due\n- outstanding_amount\n- recurring: \"Y\" (true) \"N\" (false)\n- status\n- updated\n", "parameters": [ { "name": "criteria", "in": "query", "description": "Search criteria for filtering charges. Available fields:\n- id\n- alt_key (your reference for a scheduled charge)\n- contract\n- created\n- due\n- outstanding_amount\n- recurring (Y/N)\n- status\n- updated\n\nExamples:\n- `status=ACTIVE`\n- `contract=co_12345_67890`\n- `alt_key=INSTALMENT_2`\n- `due<>2024-01-01;2024-12-31`\n- `outstanding_amount>=10`\n", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order for results. Supports any field that criteria supports.\nDefaults to `created:desc` if not specified. Append `:desc` for descending order.\nSeparate multiple order fields with commas.\n\nExamples:\n- `order=due`\n- `order=outstanding_amount:desc`\n", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Fields to expand into full objects. Separate multiple fields with commas.\n\nAvailable fields:\n- contract (contract object)\n- created_session (session object)\n- updated_session (session object)\n\nExample: `expand=contract`\n", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum records to return", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Offset from first records", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of charges", "content": { "application/json": { "schema": { "type": "object", "properties": { "charges": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/accounts/{account_id}": { "parameters": [ { "name": "account_id", "in": "path", "description": "Account ID or CRM key. When using a CRM key, operations will target the first account created with that CRM key.", "required": true, "schema": { "type": "string", "pattern": "^acc_[0-9]+_[0-9a-z]+$" } } ], "put": { "summary": "Update an account", "operationId": "updateAccount", "tags": [ "accounts" ], "description": "Update an existing account's details. When using a CRM key in the path, this endpoint will update the first account that was created with that CRM key.\n\nNote: Multiple accounts can share the same CRM key, but operations using the CRM key in the path will always target the first account created with that key.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account" ], "properties": { "account": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Account/properties/address" }, "company": { "type": "string", "description": "Company name" }, "email": { "type": "string", "description": "Email address. Invalid addresses are accepted to prevent interrupting payments due to email validation issues. Client applications can implement their own validation if needed." }, "first_name": { "type": "string", "description": "First name of the account holder" }, "last_name": { "type": "string", "description": "Last name of the account holder" }, "locale": { "type": "string", "description": "Locale of the user" }, "metadata": { "type": "object", "description": "Custom key-value pairs stored on the account", "additionalProperties": { "type": "string" } }, "phone": { "type": "string", "description": "Phone number. Any format is accepted to prevent interrupting payments due to phone validation issues. Client applications can implement their own validation if needed." }, "tags": { "type": "string", "description": "CSV of tags/references for searching" }, "timezone": { "type": "string", "description": "Timezone in IANA format" } } } } } } } }, "responses": { "200": { "description": "Updated account", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/paths/~1charges/get/responses/400" }, "401": { "description": "Invalid credentials (authentication is validated before instance key)" }, "404": { "description": "Instance not found (only checked after successful authentication)" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Basic Authentication using secret key" }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "OAuth 2.0 Bearer Token Authentication" } }, "schemas": { "Account": { "type": "object", "description": "A customer account object. Contains all information about a customer including their contact details,\nstatus, and metadata.\n\nIMPORTANT: The `bolton_values` field is managed internally by the system and should not be modified or\nreferenced directly in tests or integrations. Always use the standard top-level fields (company, email,\nphone, etc.) when creating, updating, or querying accounts.\n", "properties": { "address": { "type": "object", "description": "Address fields. All fields are optional and any values are accepted to prevent interrupting payments due to address validation issues.\nField behavior:\n1. When updating an address, the entire address object is replaced with the new values\n2. To clear/null out all address fields, set each field to an empty string\nClient applications can implement their own validation if needed.\n", "properties": { "country": { "type": "string", "description": "Country code (any format accepted). Set to empty string to clear." }, "line1": { "type": "string", "description": "First line of the address. Set to empty string to clear." }, "line2": { "type": "string", "description": "Second line of the address. Set to empty string to clear." }, "line3": { "type": "string", "description": "Third line of the address. Set to empty string to clear." }, "line4": { "type": "string", "description": "City/Town. Set to empty string to clear." }, "line5": { "type": "string", "description": "Postcode/ZIP. Set to empty string to clear." }, "line6": { "type": "string", "description": "State/Region. Set to empty string to clear." } } }, "bolton_values": { "type": "object", "description": "Enterprise Feature: Internal system values.\nThis field is only relevant for enterprise customers and should be ignored by other users.\n", "x-enterprise-only": true, "additionalProperties": true }, "channels": { "type": "array", "items": { "type": "string" }, "description": "List of channels that have permission to see this account. When an account makes a payment against a channel, they are automatically added to that channel." }, "code": { "type": "string", "description": "Account code" }, "company": { "type": "string", "description": "Company name" }, "created": { "type": "string", "format": "date-time", "description": "Account creation timestamp" }, "created_session": { "type": "string", "pattern": "^ses_[0-9]+_[0-9]+$", "description": "Session ID when the account was created" }, "crm": { "type": "string", "description": "Enterprise Feature: The CRM system identifier.\nThis field is only relevant for enterprise customers and should be ignored by other users.\n", "x-enterprise-only": true }, "crm_key": { "type": "string", "description": "Your identifier for the account" }, "disconnected_account": { "type": "boolean", "description": "Enterprise Feature: Indicates if this account is disconnected from the enterprise CRM system.\nThis field is only relevant for enterprise customers and should be ignored by other users.\n", "x-enterprise-only": true }, "divisions": { "type": "array", "items": { "type": "string" }, "description": "List of divisions that have permission to see this account. A division can be added to this list directly via the API, or is automatically added when an account makes a payment against either (1) a channel that belongs to the division or (2) an initiative that belongs to the division." }, "email": { "type": "string", "description": "Email address. Invalid addresses are accepted to prevent interrupting payments due to email validation issues. Client applications can implement their own validation if needed." }, "first_name": { "type": "string", "description": "First name of the account holder" }, "full_address": { "type": "string", "description": "Formatted full address" }, "giftaid_ineligible": { "type": "boolean", "description": "Indicates the account is excluded from Gift Aid eligibility (GB donations)" }, "id": { "type": "string", "pattern": "^acc_[0-9]+_[0-9]+$", "description": "Unique identifier for the account" }, "initiatives": { "type": "array", "items": { "type": "string" }, "description": "List of initiatives that this account has performed payments against. When an account makes a payment against an initiative, it is automatically added to this list." }, "last_name": { "type": "string", "description": "Last name of the account holder" }, "last_transacted": { "type": "string", "format": "date-time", "description": "Timestamp of last transaction" }, "last_transaction": { "type": "string", "description": "ID of last transaction" }, "locale": { "type": "string", "description": "Locale of the user" }, "metadata": { "type": "object", "description": "Custom key-value pairs stored on the account", "additionalProperties": { "type": "string" } }, "name": { "type": "string", "description": "Full name of the account holder" }, "phone": { "type": "string", "description": "Phone number. Any format is accepted to prevent interrupting payments due to phone validation issues. Client applications can implement their own validation if needed." }, "status": { "type": "string", "enum": [ "ACTIVE", "TEMP" ], "description": "Account status" }, "tags": { "type": "string", "description": "CSV of tags/references" }, "timezone": { "type": "string", "description": "Timezone in IANA format" }, "updated": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "updated_session": { "type": "string", "pattern": "^ses_[0-9]+_[0-9]+$", "description": "Session ID when the account was last updated" }, "v": { "type": "integer", "description": "Object version for optimistic concurrency control" } } } } } } ````