# Callback to update or create a full shopper account > Create or update a shopper account with profile information, payment and addresses. This is also known as the "upsert account" API, a combination of update and insert. Source: https://help.boltapp.com/api-reference/embeddable-checkout-v3/callbacks/callbackaccountupsert `POST /callbacks/accounts` ## OpenAPI definition This endpoint as it appears in the OpenAPI document, with every schema it references included. ```json { "openapi": "3.2.0", "info": { "version": "3.3.22", "title": "Bolt API Reference", "description": "A comprehensive Bolt API reference for interacting with Accounts, Payments, Orders and more.", "termsOfService": "https://www.boltapp.com/end-user-terms", "contact": { "name": "Bolt", "email": "merchantsupport@boltapp.com", "url": "https://help.boltapp.com/api-bolt/" } }, "servers": [ { "url": "https://{environment}.boltapp.com/v3", "variables": { "environment": { "enum": [ "api", "api-sandbox" ], "default": "api-sandbox" } } } ], "paths": { "/callbacks/accounts": { "post": { "x-speakeasy-ignore": true, "summary": "Callback to update or create a full shopper account", "operationId": "callbackAccountUpsert", "description": "Create or update a shopper account with profile information, payment and addresses. This is also known as the \"upsert account\" API, a combination of update and insert.", "tags": [ "Callbacks" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/x-bolt-hmac-sha256" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-full-account" } } } }, "responses": { "200": { "description": "The account details were successfully created/updated" }, "4XX": { "description": "An error has occurred, and further details are contained in the response." }, "default": { "description": "An error has occurred, and further details are contained in the response." } } } } }, "components": { "parameters": { "x-bolt-hmac-sha256": { "description": "A Bolt-signed hash-based message authentication code (HMAC) to verify that the sender is Bolt.", "in": "header", "name": "X-Bolt-Hmac-Sha256", "required": true, "schema": { "type": "string" } } }, "schemas": { "create-full-account": { "type": "object", "properties": { "account_details": { "$ref": "#/components/schemas/account" }, "customer_data_id": { "type": "string", "description": "A unique identifier for this account on your cart platform.", "examples": [ "5FEB9028D" ] } } }, "account": { "type": "object", "required": [ "addresses", "payment_methods" ], "properties": { "addresses": { "type": "array", "description": "A list of addresses associated with this account. These can be considered the \"shipping addresses\". The account's visible addresses are filtered according to the configured shipping destinations in your Bolt merchant dashboard. If no account addresses are available, use the billing address of the selected payment method.", "items": { "$ref": "#/components/schemas/address-listing" } }, "payment_methods": { "type": "array", "description": "A list of payment methods associated with this account. The account's visible payment methods are filtered to include only cards that are chargeable.", "items": { "$ref": "#/components/schemas/payment-method" } }, "profile": { "$ref": "#/components/schemas/profile" } } }, "address-listing": { "type": "object", "description": "An address saved on an account, i.e. a physical address plus any additional account-specific metadata.", "required": [ "first_name", "last_name", "street_address1", "locality", "postal_code", "country_code" ], "properties": { "id": { "type": "string", "format": "id", "description": "The address's unique identifier.", "readOnly": true, "x-order": 1, "examples": [ "D4g3h5tBuVYK9" ] }, "first_name": { "type": "string", "description": "The first name of the person associated with this address.", "x-order": 2, "examples": [ "Alice" ] }, "last_name": { "type": "string", "description": "The last name of the person associated with this address.", "x-order": 3, "examples": [ "Baker" ] }, "company": { "type": "string", "description": "The company associated with this address.", "x-order": 4, "examples": [ "ACME Corporation" ] }, "street_address1": { "type": "string", "description": "The street address associated with this address.", "x-order": 5, "examples": [ "535 Mission St, Ste 1401" ] }, "street_address2": { "type": "string", "description": "Any additional, optional, street address information associated with this address.", "x-order": 6, "examples": [ "c/o Shipping Department" ] }, "locality": { "type": "string", "description": "The locality (e.g. city, town, etc...) associated with this address.", "x-order": 7, "examples": [ "San Francisco" ] }, "postal_code": { "type": "string", "description": "The postal code associated with this address.", "x-order": 8, "examples": [ "94105" ] }, "region": { "type": "string", "description": "The region or administrative area (e.g. state, province, county, etc...) associated with this address.", "x-order": 9, "examples": [ "CA" ] }, "country_code": { "$ref": "#/components/schemas/country-code" }, "email": { "type": "string", "format": "email", "description": "The email address associated with this address.", "x-order": 11, "examples": [ "alice@example.com" ] }, "phone": { "type": "string", "format": "phone", "description": "The phone number associated with this address.", "x-oapi-codegen-extra-tags": { "validate": "phone=strict" }, "x-order": 12, "examples": [ "+14155550199" ] }, "is_default": { "type": "boolean", "description": "Whether or not this is the default address saved.", "readOnly": true, "examples": [ true ] } } }, "country-code": { "type": "string", "description": "The country (in its ISO 3166 alpha-2 format) associated with this address.", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BS", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "x-oapi-codegen-extra-tags": { "validate": "country,required" }, "x-order": 11, "examples": [ "US" ] }, "payment-method": { "oneOf": [ { "$ref": "#/components/schemas/payment-method-credit-card" }, { "$ref": "#/components/schemas/payment-method-googlepay" }, { "$ref": "#/components/schemas/payment-method-applepay" }, { "$ref": "#/components/schemas/payment-method-paypal" }, { "$ref": "#/components/schemas/payment-method-affirm" }, { "$ref": "#/components/schemas/payment-method-afterpay" }, { "$ref": "#/components/schemas/payment-method-klarna" }, { "$ref": "#/components/schemas/payment-method-klarna-account" }, { "$ref": "#/components/schemas/payment-method-klarna-paynow" } ], "discriminator": { "propertyName": ".tag", "mapping": { "credit_card": "#/components/schemas/payment-method-credit-card", "googlepay": "#/components/schemas/payment-method-googlepay", "applepay": "#/components/schemas/payment-method-applepay", "paypal": "#/components/schemas/payment-method-paypal", "affirm": "#/components/schemas/payment-method-affirm", "afterpay": "#/components/schemas/payment-method-afterpay", "klarna": "#/components/schemas/payment-method-klarna", "klarna_account": "#/components/schemas/payment-method-klarna-account", "klarna_paynow": "#/components/schemas/payment-method-klarna-paynow" } } }, "payment-method-credit-card": { "title": "Credit Card Payment Method", "allOf": [ { "type": "object", "required": [ ".tag", "type", "billing_address" ], "properties": { ".tag": { "type": "string", "enum": [ "credit_card" ], "x-order": 0, "examples": [ "credit_card" ] }, "id": { "type": "string", "format": "id", "readOnly": true, "x-order": 1, "examples": [ "X5h6j8uLpVGK" ] }, "type": { "type": "string", "description": "The type of payment method", "x-order": 2, "examples": [ "credit_card" ] }, "billing_address": { "$ref": "#/components/schemas/address-reference" } } }, { "$ref": "#/components/schemas/credit-card" } ] }, "address-reference": { "oneOf": [ { "$ref": "#/components/schemas/address-reference-id" }, { "$ref": "#/components/schemas/address-reference-explicit" }, { "$ref": "#/components/schemas/address-reference-partial" } ], "discriminator": { "propertyName": ".tag", "mapping": { "id": "#/components/schemas/address-reference-id", "explicit": "#/components/schemas/address-reference-explicit", "partial": "#/components/schemas/address-reference-partial" } } }, "address-reference-id": { "type": "object", "title": "Address ID Reference", "required": [ ".tag", "id" ], "properties": { ".tag": { "type": "string", "enum": [ "id" ], "description": "The type of address reference", "examples": [ "id" ] }, "id": { "type": "string", "format": "id", "description": "The address's ID", "examples": [ "D4g3h5tBuVYK9" ] } } }, "address-reference-explicit": { "type": "object", "title": "Explicit Address Reference", "required": [ ".tag", "first_name", "last_name", "street_address1", "locality", "postal_code", "country_code" ], "properties": { ".tag": { "type": "string", "enum": [ "explicit" ], "description": "The type of address reference", "x-order": 0, "examples": [ "explicit" ] }, "id": { "type": "string", "format": "id", "description": "The address's unique identifier.", "readOnly": true, "x-order": 1, "examples": [ "D4g3h5tBuVYK9" ] }, "first_name": { "type": "string", "description": "The first name of the person associated with this address.", "x-order": 2, "examples": [ "Alice" ] }, "last_name": { "type": "string", "description": "The last name of the person associated with this address.", "x-order": 3, "examples": [ "Baker" ] }, "company": { "type": "string", "description": "The company associated with this address.", "x-order": 4, "examples": [ "ACME Corporation" ] }, "street_address1": { "type": "string", "description": "The street address associated with this address.", "x-order": 5, "examples": [ "535 Mission St, Ste 1401" ] }, "street_address2": { "type": "string", "description": "Any additional, optional, street address information associated with this address.", "x-order": 6, "examples": [ "c/o Shipping Department" ] }, "locality": { "type": "string", "description": "The locality (e.g. city, town, etc...) associated with this address.", "x-order": 7, "examples": [ "San Francisco" ] }, "postal_code": { "type": "string", "description": "The postal code associated with this address.", "x-order": 8, "examples": [ "94105" ] }, "region": { "type": "string", "description": "The region or administrative area (e.g. state, province, county, etc...) associated with this address.", "x-order": 9, "examples": [ "CA" ] }, "country_code": { "$ref": "#/components/schemas/country-code" }, "email": { "type": "string", "format": "email", "description": "The email address associated with this address.", "x-order": 11, "examples": [ "alice@example.com" ] }, "phone": { "type": "string", "format": "phone", "description": "The phone number associated with this address.", "x-order": 12, "examples": [ "+14155550199" ] } } }, "address-reference-partial": { "type": "object", "title": "Partial Address Reference", "required": [ ".tag", "postal_code" ], "properties": { ".tag": { "type": "string", "enum": [ "partial" ], "description": "The type of address reference", "x-order": 0, "examples": [ "partial" ] }, "postal_code": { "type": "string", "description": "The postal code associated with the credit card billing address.", "x-order": 1, "examples": [ "94105" ] } } }, "credit-card": { "required": [ "network", "bin", "last4", "expiration", "token" ], "type": "object", "properties": { "network": { "$ref": "#/components/schemas/credit-card-network" }, "bin": { "type": "string", "description": "The Bank Identification Number (BIN). This is the first 4 to 8 digits of the account number.", "pattern": "^\\d+$", "examples": [ "411111" ] }, "last4": { "type": "string", "description": "The account number's last four digits.", "pattern": "^\\d{4}$", "examples": [ "1004" ] }, "expiration": { "type": "string", "description": "The expiration date, in YYYY-MM format.", "pattern": "^\\d{4}-\\d{2}$", "examples": [ "2029-03" ] }, "token": { "type": "string", "description": "The Bolt token associated with the credit card.", "writeOnly": true, "examples": [ "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0" ] }, "affirm_vcn_token": { "type": "string", "description": "The checkout token associated with Affirm VCN credit cards.", "examples": [ "a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0" ] }, "default": { "type": "boolean", "description": "Indicates whether this credit card is the default payment method.", "examples": [ true ] } } }, "credit-card-network": { "type": "string", "description": "The credit card's network.", "enum": [ "visa", "mastercard", "amex", "discover", "jcb", "dinersclub", "unionpay", "alliancedata", "citiplcc" ], "x-oapi-codegen-extra-tags": { "validate": "required" }, "examples": [ "visa" ] }, "payment-method-googlepay": { "title": "Googlepay Payment Method", "allOf": [ { "type": "object", "required": [ ".tag", "type" ], "properties": { ".tag": { "type": "string", "enum": [ "googlepay" ], "x-order": 0, "examples": [ "googlepay" ] }, "id": { "type": "string", "format": "id", "readOnly": true, "x-order": 1, "examples": [ "X5h6j8uLpVGK" ] }, "type": { "type": "string", "description": "The type of payment method", "x-order": 2, "examples": [ "googlepay" ] }, "billing_address": { "$ref": "#/components/schemas/address-reference" } } }, { "$ref": "#/components/schemas/credit-card" } ] }, "payment-method-applepay": { "title": "ApplePay Payment Method", "allOf": [ { "type": "object", "required": [ ".tag", "type" ], "properties": { ".tag": { "type": "string", "enum": [ "applepay" ], "x-order": 0, "examples": [ "applepay" ] }, "id": { "type": "string", "format": "id", "readOnly": true, "x-order": 1, "examples": [ "X5h6j8uLpVGK" ] }, "type": { "type": "string", "description": "The type of payment method", "x-order": 2, "examples": [ "applepay" ] }, "billing_address": { "$ref": "#/components/schemas/address-reference" } } }, { "$ref": "#/components/schemas/credit-card" }, { "type": "object", "properties": { "bolt_reference": { "type": "string", "description": "Bolt generated Applepay token id needed for token life cycle management.", "examples": [ "a6f57b8c-3b12-4baf-9e77-0b9b2e3cb3d7" ] } } } ] }, "payment-method-paypal": { "type": "object", "title": "PayPal Payment Method", "required": [ ".tag", "success_url", "cancel_url" ], "properties": { ".tag": { "type": "string", "enum": [ "paypal" ], "x-order": 0, "examples": [ "paypal" ] }, "success_url": { "type": "string", "description": "Redirect URL for successful PayPal transaction.", "format": "url", "writeOnly": true, "examples": [ "https://www.example.com/paypal-callback/success" ] }, "cancel_url": { "type": "string", "description": "Redirect URL for canceled PayPal transaction.", "format": "url", "writeOnly": true, "examples": [ "https://www.example.com/paypal-callback/cancel" ] } } }, "payment-method-affirm": { "type": "object", "required": [ ".tag", "return_url" ], "title": "Affirm Payment Method", "properties": { ".tag": { "type": "string", "enum": [ "affirm" ], "examples": [ "affirm" ] }, "return_url": { "type": "string", "description": "Return URL to return to after payment completion in Affirm.", "format": "url", "writeOnly": true, "examples": [ "https://www.example.com/handle_affirm_success" ] } } }, "payment-method-afterpay": { "type": "object", "required": [ ".tag", "return_url" ], "title": "Afterpay Payment Method", "properties": { ".tag": { "type": "string", "enum": [ "afterpay" ], "examples": [ "afterpay" ] }, "return_url": { "type": "string", "description": "Return URL to return to after payment completion in Afterpay.", "format": "url", "writeOnly": true, "examples": [ "https://www.example.com/handle_afterpay_success" ] } } }, "payment-method-klarna": { "type": "object", "required": [ ".tag", "return_url" ], "title": "Klarna Payment Method", "properties": { ".tag": { "type": "string", "enum": [ "klarna" ], "examples": [ "klarna" ] }, "return_url": { "type": "string", "description": "Return URL to return to after payment completion in Klarna.", "format": "url", "writeOnly": true, "examples": [ "https://www.example.com/handle_klarna_success" ] } } }, "payment-method-klarna-account": { "type": "object", "required": [ ".tag", "return_url" ], "title": "Klarna Account Payment Method", "properties": { ".tag": { "type": "string", "enum": [ "klarna_account" ], "examples": [ "klarna_account" ] }, "return_url": { "type": "string", "description": "Return URL to return to after payment completion in Klarna.", "format": "url", "writeOnly": true, "examples": [ "https://www.example.com/handle_klarna_account_success" ] } } }, "payment-method-klarna-paynow": { "type": "object", "required": [ ".tag", "return_url" ], "title": "Klarna Pay Now Payment Method", "properties": { ".tag": { "type": "string", "enum": [ "klarna_paynow" ], "examples": [ "klarna_paynow" ] }, "return_url": { "type": "string", "description": "Return URL to return to after payment completion in Klarna.", "format": "url", "writeOnly": true, "examples": [ "https://www.example.com/handle_klarna_paynow_success" ] } } }, "profile": { "type": "object", "description": "An account's identifying information.", "required": [ "first_name", "last_name", "email" ], "properties": { "first_name": { "type": "string", "description": "The given name of the person associated with this profile.", "x-order": 1, "examples": [ "Alice" ] }, "last_name": { "type": "string", "description": "The last name of the person associated with this profile.", "x-order": 2, "examples": [ "Baker" ] }, "email": { "type": "string", "format": "email", "description": "The email address asscoiated with this profile.", "x-order": 3, "examples": [ "alice@example.com" ] }, "phone": { "type": "string", "format": "phone", "description": "The phone number associated with this profile.", "x-order": 4, "examples": [ "+14155550199" ] } } } }, "securitySchemes": { "api-key": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "oauth": { "flows": { "authorizationCode": { "authorizationUrl": "/v1/oauth/authorize", "refreshUrl": "/v1/oauth/token", "tokenUrl": "/v1/oauth/token", "scopes": { "bolt.account.manage": "This scope grants permissions to perform read/edit/delete actions on Bolt Account data", "bolt.account.view": "This scope grants permissions to perform read only actions on Bolt Account data", "openid": "This scope grants permissions that enable Bolt Single Sign-On (SSO) by granting a JSON Web Token (JWT) that stores account data." } } }, "type": "oauth2" } } } } ```