{ "openapi" : "3.0.1", "info" : { "title" : "Commerce Payments Settings", "description" : "Basepom for all HubSpot Projects", "version" : "2027-03-beta", "x-hubspot-product-tier-requirements" : { "marketing" : "FREE", "sales" : "FREE", "service" : "FREE", "cms" : "FREE", "commerce" : "FREE", "crmHub" : "FREE", "dataHub" : "FREE" } }, "servers" : [ { "url" : "https://api.hubapi.com" } ], "tags" : [ { "name" : "Basic" } ], "paths" : { "/commerce/payments-settings/2027-03-beta/payments-settings/billing" : { "get" : { "tags" : [ "Basic" ], "summary" : "Retrieve billing settings", "description" : "Retrieve the current billing settings for your HubSpot account's payment settings. This endpoint allows you to access billing configurations, which can be useful for managing and reviewing your account's payment setup.", "operationId" : "get-/commerce/payments-settings/2027-03-beta/payments-settings/billing", "parameters" : [ ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/GetBillingSettingsPublicResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.objects.invoices.read" ] }, { "oauth2" : [ "crm.schemas.invoices.read" ] }, { "oauth2" : [ "cpq.quotes.write" ] }, { "oauth2" : [ "crm.objects.quotes.read" ] }, { "oauth2" : [ "crm.schemas.quotes.read" ] }, { "oauth2" : [ "cpq.quotes.read" ] }, { "oauth2" : [ "crm.objects.subscriptions.read" ] }, { "oauth2" : [ "crm.schemas.subscriptions.read" ] } ] }, "patch" : { "tags" : [ "Basic" ], "summary" : "Update billing settings", "description" : "Update the billing settings for your HubSpot account's payment settings. This endpoint allows you to modify the billing configurations, which can be essential for managing how payments are processed and billed. Ensure you have the necessary permissions to write payment checkout settings before making changes.", "operationId" : "patch-/commerce/payments-settings/2027-03-beta/payments-settings/billing", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateBillingSettingsPublicRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/GetBillingSettingsPublicResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ ] } }, "/commerce/payments-settings/2027-03-beta/payments-settings/checkout-fees" : { "get" : { "tags" : [ "Basic" ], "summary" : "Retrieve checkout fees", "description" : "Retrieve the current checkout fee settings for your HubSpot account. This endpoint provides information about any fees applied during the checkout process, which can be useful for understanding transaction costs and configuring payment settings.", "operationId" : "get-/commerce/payments-settings/2027-03-beta/payments-settings/checkout-fees", "parameters" : [ ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/GetCheckoutFeesPublicResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.objects.invoices.read" ] }, { "oauth2" : [ "crm.schemas.invoices.read" ] }, { "oauth2" : [ "cpq.quotes.write" ] }, { "oauth2" : [ "crm.objects.quotes.read" ] }, { "oauth2" : [ "crm.schemas.quotes.read" ] }, { "oauth2" : [ "cpq.quotes.read" ] }, { "oauth2" : [ "crm.objects.subscriptions.read" ] }, { "oauth2" : [ "crm.schemas.subscriptions.read" ] } ] }, "patch" : { "tags" : [ "Basic" ], "summary" : "Update checkout fees", "description" : "Update the checkout fees settings in your HubSpot account. This endpoint allows you to modify the configuration of checkout fees, which can be useful for adjusting fee structures or implementing new pricing strategies. Ensure that the request body contains the necessary details for the update.", "operationId" : "patch-/commerce/payments-settings/2027-03-beta/payments-settings/checkout-fees", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateCheckoutFeesPublicRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/GetCheckoutFeesPublicResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ ] } }, "/commerce/payments-settings/2027-03-beta/payments-settings/checkout-fees/{checkoutFeeId}" : { "delete" : { "tags" : [ "Basic" ], "summary" : "Delete checkout fee", "description" : "Remove a specific checkout fee from the payments settings in your HubSpot account. This operation is useful for managing and updating the fees associated with checkout processes. Ensure you have the necessary permissions to perform this action.", "operationId" : "delete-/commerce/payments-settings/2027-03-beta/payments-settings/checkout-fees/{checkoutFeeId}", "parameters" : [ { "name" : "checkoutFeeId", "in" : "path", "description" : "The unique identifier of the checkout fee to delete.", "required" : true, "style" : "simple", "explode" : false, "schema" : { "type" : "string", "example" : null } } ], "responses" : { "204" : { "description" : "No content", "content" : { } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ ] } }, "/commerce/payments-settings/2027-03-beta/payments-settings/policy" : { "get" : { "tags" : [ "Basic" ], "summary" : "Retrieve policy settings", "description" : "Retrieve the current payment policy settings for your HubSpot account. This endpoint provides access to the policy configurations related to payment settings, allowing you to review the existing setup. It is useful for ensuring compliance with organizational or regulatory requirements by reviewing the policy settings in place.", "operationId" : "get-/commerce/payments-settings/2027-03-beta/payments-settings/policy", "parameters" : [ ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/GetPolicySettingsPublicResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.objects.invoices.read" ] }, { "oauth2" : [ "crm.schemas.invoices.read" ] }, { "oauth2" : [ "cpq.quotes.write" ] }, { "oauth2" : [ "crm.objects.quotes.read" ] }, { "oauth2" : [ "crm.schemas.quotes.read" ] }, { "oauth2" : [ "cpq.quotes.read" ] }, { "oauth2" : [ "crm.objects.subscriptions.read" ] }, { "oauth2" : [ "crm.schemas.subscriptions.read" ] } ] }, "patch" : { "tags" : [ "Basic" ], "summary" : "Update policy settings", "description" : "Update the payment policy settings for your HubSpot account. This endpoint allows you to modify existing policy configurations, which can include terms and conditions related to payments. Ensure that you have the necessary permissions to write payment checkout settings before making changes.", "operationId" : "patch-/commerce/payments-settings/2027-03-beta/payments-settings/policy", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdatePolicySettingsPublicRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/GetPolicySettingsPublicResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ ] } }, "/commerce/payments-settings/2027-03-beta/payments-settings/shipping" : { "get" : { "tags" : [ "Basic" ], "summary" : "Retrieve shipping settings", "description" : "Retrieve the current shipping settings for your HubSpot account. This endpoint provides information about the configured shipping options, which can be useful for managing and reviewing your shipping policies and configurations.", "operationId" : "get-/commerce/payments-settings/2027-03-beta/payments-settings/shipping", "parameters" : [ ], "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/GetShippingSettingsPublicResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ { "oauth2" : [ "crm.objects.invoices.read" ] }, { "oauth2" : [ "crm.schemas.invoices.read" ] }, { "oauth2" : [ "cpq.quotes.write" ] }, { "oauth2" : [ "crm.objects.quotes.read" ] }, { "oauth2" : [ "crm.schemas.quotes.read" ] }, { "oauth2" : [ "cpq.quotes.read" ] }, { "oauth2" : [ "crm.objects.subscriptions.read" ] }, { "oauth2" : [ "crm.schemas.subscriptions.read" ] } ] }, "patch" : { "tags" : [ "Basic" ], "summary" : "Update shipping settings", "description" : "Update the shipping settings for your HubSpot account. This endpoint allows you to modify existing shipping configurations to better suit your business needs. Ensure that the request body contains the necessary fields as defined in the UpdateShippingSettingsPublicRequest schema.", "operationId" : "patch-/commerce/payments-settings/2027-03-beta/payments-settings/shipping", "parameters" : [ ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateShippingSettingsPublicRequest" }, "example" : null } }, "required" : true }, "responses" : { "200" : { "description" : "successful operation", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/GetShippingSettingsPublicResponse" }, "example" : null } } }, "default" : { "description" : "", "$ref" : "#/components/responses/Error" } }, "security" : [ ] } } }, "components" : { "schemas" : { "CheckoutFeePublic" : { "required" : [ "appliesToPaymentType", "feeValue", "feeValueType", "id", "name" ], "type" : "object", "properties" : { "appliesToPaymentType" : { "type" : "string", "description" : "The type of payment to which this fee applies, represented as a string.", "example" : null }, "feeValue" : { "type" : "number", "description" : "The numerical value of the fee, indicating the amount to be charged.", "example" : null }, "feeValueType" : { "type" : "string", "description" : "The type of the fee value, represented as a string, which defines how the fee value is interpreted (e.g., as a percentage or a fixed amount).", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier for this checkout fee configuration.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the checkout fee, used for identification and display purposes.", "example" : null } }, "example" : null }, "CheckoutFeePublicUpdateRequest" : { "required" : [ "appliesToPaymentType", "feeValue", "feeValueType", "name" ], "type" : "object", "properties" : { "appliesToPaymentType" : { "type" : "string", "description" : "The type of payment to which the checkout fee applies, represented as a string.", "example" : null }, "feeValue" : { "type" : "number", "description" : "The value of the checkout fee. This is a numeric value.", "example" : null }, "feeValueType" : { "type" : "string", "description" : "The type of the fee value, represented as a string.", "example" : null }, "id" : { "type" : "string", "description" : "The unique identifier for the checkout fee. This is a string value.", "example" : null }, "name" : { "type" : "string", "description" : "The name of the checkout fee. This is a string value.", "example" : null } }, "example" : null }, "Error" : { "required" : [ "category", "correlationId", "message" ], "type" : "object", "properties" : { "category" : { "type" : "string", "description" : "The error category.", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "description" : "Context about the error condition, represented as an object with additional properties.", "example" : "{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}" }, "correlationId" : { "type" : "string", "description" : "A unique identifier for the request. Include this value with any error reports or support tickets. Format: UUID.", "format" : "uuid", "example" : "aeb5f871-7f07-4993-9211-075dc63e7cbf" }, "errors" : { "type" : "array", "description" : "Further information about the error, represented as an array of ErrorDetail objects.", "example" : null, "items" : { "$ref" : "#/components/schemas/ErrorDetail" } }, "links" : { "type" : "object", "additionalProperties" : { "type" : "string", "example" : null }, "description" : "A map of link names to associated URIs containing documentation about the error or recommended remediation steps.", "example" : null }, "message" : { "type" : "string", "description" : "A human readable message describing the error along with remediation steps where appropriate.", "example" : "An error occurred" }, "subCategory" : { "type" : "string", "description" : "A specific category that contains more specific detail about the error.", "example" : null } }, "description" : "Represents an error response returned by the API when an operation fails. This component is used in various endpoints to provide detailed information about the error encountered.", "example" : { "message" : "Invalid input (details will vary based on the error)", "correlationId" : "aeb5f871-7f07-4993-9211-075dc63e7cbf", "category" : "VALIDATION_ERROR", "links" : { "knowledge-base" : "https://www.hubspot.com/products/service/knowledge-base" } } }, "ErrorDetail" : { "required" : [ "message" ], "type" : "object", "properties" : { "code" : { "type" : "string", "description" : "The status code associated with the error detail, represented as a string.", "example" : null }, "context" : { "type" : "object", "additionalProperties" : { "type" : "array", "example" : null, "items" : { "type" : "string", "example" : null } }, "description" : "Context about the error condition, represented as an object. It may include additional properties, each containing an array of strings, to provide more detailed information about the error.", "example" : "{missingScopes=[scope1, scope2]}" }, "in" : { "type" : "string", "description" : "The name of the field or parameter in which the error was found. It is a string that helps identify the source of the error.", "example" : null }, "message" : { "type" : "string", "description" : "A human readable message describing the error along with remediation steps where appropriate. This is a required field.", "example" : null }, "subCategory" : { "type" : "string", "description" : "A specific category that contains more specific detail about the error, providing further classification.", "example" : null } }, "description" : "Represents detailed information about an error that occurred in the API. This component is used to provide additional context and specifics about errors, typically as part of an error response.", "example" : null }, "GetBillingSettingsPublicResponse" : { "required" : [ "checkoutPrefillEnabled", "collectFullBillingAddress", "collectPaymentMethodOnFile", "defaultFromEmailAddress", "paymentsGoogleAnalyticsEnabled", "recaptchaEnabled" ], "type" : "object", "properties" : { "accountGoogleAnalyticsEnabled" : { "type" : "boolean", "description" : "Indicates whether Google Analytics tracking is enabled for the account. A boolean value.", "example" : null }, "checkoutPrefillEnabled" : { "type" : "boolean", "description" : "Indicates whether checkout fields should be prefilled. A boolean value.", "example" : null }, "collectFullBillingAddress" : { "type" : "boolean", "description" : "Indicates whether the full billing address should be collected. A boolean value.", "example" : null }, "collectPaymentMethodOnFile" : { "type" : "boolean", "description" : "Indicates whether a payment method should be kept on file. A boolean value.", "example" : null }, "defaultFromEmailAddress" : { "type" : "string", "description" : "The default email address used for sending communications. A string value.", "example" : "testData@email.com" }, "paymentsGoogleAnalyticsEnabled" : { "type" : "boolean", "description" : "Indicates whether Google Analytics tracking is enabled for payments. A boolean value.", "example" : null }, "recaptchaEnabled" : { "type" : "boolean", "description" : "Indicates whether reCAPTCHA is enabled for additional security. A boolean value.", "example" : null } }, "example" : null }, "GetCheckoutFeesPublicResponse" : { "required" : [ "checkoutFees" ], "type" : "object", "properties" : { "checkoutFees" : { "type" : "array", "description" : "An array of CheckoutFeePublic objects, each representing a specific fee applied during the checkout process.", "example" : null, "items" : { "$ref" : "#/components/schemas/CheckoutFeePublic" } } }, "example" : null }, "GetPolicySettingsPublicResponse" : { "required" : [ "acknowledgementRequired", "customPolicyEnabled" ], "type" : "object", "properties" : { "acknowledgementRequired" : { "type" : "boolean", "description" : "A boolean indicating whether an acknowledgement is required for the policy.", "example" : null }, "cancellationPolicyText" : { "type" : "string", "description" : "A string containing the text of the cancellation policy.", "example" : null }, "customPolicyEnabled" : { "type" : "boolean", "description" : "A boolean indicating whether a custom policy is enabled.", "example" : null }, "refundPolicyText" : { "type" : "string", "description" : "A string containing the text of the refund policy.", "example" : null }, "termsOfServiceUrl" : { "type" : "string", "description" : "A string representing the URL of the terms of service.", "example" : null } }, "example" : null }, "GetShippingSettingsPublicResponse" : { "required" : [ "collectShippingAddressByDefault", "countriesShippedTo" ], "type" : "object", "properties" : { "collectShippingAddressByDefault" : { "type" : "boolean", "description" : "A boolean indicating whether the shipping address is collected by default.", "example" : null }, "countriesShippedTo" : { "type" : "array", "description" : "An array of strings representing the list of countries to which shipping is available. Two digit ISO country codes are used.", "example" : null, "items" : { "type" : "string", "example" : null } } }, "example" : null }, "UpdateBillingSettingsPublicRequest" : { "required" : [ "defaultFromEmailAddress" ], "type" : "object", "properties" : { "checkoutPrefillEnabled" : { "type" : "boolean", "description" : "A boolean indicating whether checkout forms should be pre-filled with known customer information.", "example" : null }, "collectFullBillingAddress" : { "type" : "boolean", "description" : "A boolean indicating whether the full billing address should be collected during the checkout process.", "example" : null }, "collectPaymentMethodOnFile" : { "type" : "boolean", "description" : "A boolean indicating whether the payment method should be stored on file for future transactions.", "example" : null }, "defaultFromEmailAddress" : { "type" : "object", "properties" : { }, "description" : "An object representing the default email address used for sending communications related to billing.", "example" : null }, "paymentsGoogleAnalyticsEnabled" : { "type" : "boolean", "description" : "A boolean indicating whether Google Analytics tracking is enabled for payment transactions.", "example" : null }, "recaptchaEnabled" : { "type" : "boolean", "description" : "A boolean indicating whether reCAPTCHA is enabled during the checkout process to prevent fraudulent activities.", "example" : null } }, "example" : null }, "UpdateCheckoutFeesPublicRequest" : { "required" : [ "checkoutFees" ], "type" : "object", "properties" : { "checkoutFees" : { "type" : "array", "description" : "An array of checkout fee objects to be updated. Each object must conform to the CheckoutFeePublicUpdateRequest schema.", "example" : null, "items" : { "$ref" : "#/components/schemas/CheckoutFeePublicUpdateRequest" } } }, "example" : null }, "UpdatePolicySettingsPublicRequest" : { "required" : [ "cancellationPolicyText", "refundPolicyText", "termsOfServiceUrl" ], "type" : "object", "properties" : { "acknowledgementRequired" : { "type" : "boolean", "description" : "A boolean that specifies if acknowledgement is required for the policy.", "example" : null }, "cancellationPolicyText" : { "type" : "object", "properties" : { }, "description" : "An object containing the text of the cancellation policy.", "example" : null }, "customPolicyEnabled" : { "type" : "boolean", "description" : "A boolean indicating whether a custom policy is enabled.", "example" : null }, "refundPolicyText" : { "type" : "object", "properties" : { }, "description" : "An object containing the text of the refund policy.", "example" : null }, "termsOfServiceUrl" : { "type" : "object", "properties" : { }, "description" : "An object representing the URL for the terms of service.", "example" : null } }, "example" : null }, "UpdateShippingSettingsPublicRequest" : { "required" : [ "countriesShippedTo" ], "type" : "object", "properties" : { "collectShippingAddressByDefault" : { "type" : "boolean", "description" : "A boolean indicating whether the shipping address should be collected by default.", "example" : null }, "countriesShippedTo" : { "type" : "object", "properties" : { }, "description" : "An object representing the countries to which shipments are allowed. The structure of this object is not detailed in the specification.", "example" : null } }, "example" : null } }, "responses" : { "Error" : { "description" : "An error occurred.", "content" : { "*/*" : { "schema" : { "$ref" : "#/components/schemas/Error" }, "example" : null } } } }, "securitySchemes" : { "developer_hapikey" : { "type" : "apiKey", "name" : "hapikey", "in" : "query" }, "oauth2" : { "type" : "oauth2", "flows" : { "authorizationCode" : { "authorizationUrl" : "https://app.hubspot.com/oauth/authorize", "tokenUrl" : "https://api.hubapi.com/oauth/v1/token", "scopes" : { "cpq.quotes.read" : "", "cpq.quotes.write" : "", "crm.objects.invoices.read" : "", "crm.objects.quotes.read" : "", "crm.objects.subscriptions.read" : "", "crm.schemas.invoices.read" : "", "crm.schemas.quotes.read" : "", "crm.schemas.subscriptions.read" : "" } } } }, "private_apps" : { "type" : "apiKey", "name" : "private-app", "in" : "header" }, "private_apps_legacy" : { "type" : "apiKey", "name" : "private-app-legacy", "in" : "header" } } }, "x-hubspot-product-tier-requirements" : { "marketing" : "FREE", "sales" : "FREE", "service" : "FREE", "cms" : "FREE", "commerce" : "FREE", "crmHub" : "FREE", "dataHub" : "FREE" } }