{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Commerce Payments",
    "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" : "Advanced"
  } ],
  "paths" : {
    "/commerce/payments/2027-03-beta/manual-payments" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "summary" : "Create Payment",
        "description" : "Create a manual payment in the HubSpot system. This endpoint allows you to specify details such as the payment amount, currency, payment method, and date. It is useful for recording payments that occur outside of automated systems, ensuring all payment data is captured within HubSpot.",
        "operationId" : "post-/commerce/payments/2027-03-beta/manual-payments_/commerce/payments/2027-03-beta/manual-payments",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/CreateManualPaymentPublicRequest"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/CreateManualPaymentPublicResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "crm.objects.commercepayments.write" ]
        }, {
          "oauth2" : [ "crm.schemas.commercepayments.write" ]
        } ]
      }
    },
    "/commerce/payments/2027-03-beta/{paymentCrmObjectId}/actions/retry/async" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "summary" : "Retry Payment",
        "description" : "Initiate an asynchronous retry of a payment associated with the specified CRM object ID. This endpoint is useful for attempting to process payments that may have previously failed or require reprocessing. Upon successful initiation, a task locator is returned to track the status of the retry operation.",
        "operationId" : "post-/commerce/payments/2027-03-beta/{paymentCrmObjectId}/actions/retry/async_/commerce/payments/2027-03-beta/{paymentCrmObjectId}/actions/retry/async",
        "parameters" : [ {
          "name" : "paymentCrmObjectId",
          "in" : "path",
          "description" : "The unique identifier of the payment CRM object to retry.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        } ],
        "responses" : {
          "202" : {
            "description" : "accepted",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/TaskLocator"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "crm.objects.commercepayments.write" ]
        }, {
          "oauth2" : [ "crm.schemas.commercepayments.write" ]
        } ]
      }
    },
    "/commerce/payments/2027-03-beta/{paymentCrmObjectId}/actions/retry/async/tasks/{taskId}/status" : {
      "get" : {
        "tags" : [ "Advanced" ],
        "summary" : "Retrieve status",
        "description" : "Retrieve the status of a specific asynchronous retry task for a payment CRM object. This endpoint allows you to check the progress or completion status of a task that was initiated to retry a payment action.",
        "operationId" : "get-/commerce/payments/2027-03-beta/{paymentCrmObjectId}/actions/retry/async/tasks/{taskId}/status_/commerce/payments/2027-03-beta/{paymentCrmObjectId}/actions/retry/async/tasks/{taskId}/status",
        "parameters" : [ {
          "name" : "paymentCrmObjectId",
          "in" : "path",
          "description" : "The unique identifier of the payment CRM object associated with the task.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        }, {
          "name" : "taskId",
          "in" : "path",
          "description" : "The unique identifier of the task whose status is being retrieved.",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ActionResponseWithSingleResultSimplePublicObject"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "crm.objects.commercepayments.write" ]
        }, {
          "oauth2" : [ "crm.schemas.commercepayments.write" ]
        } ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "ActionResponseWithSingleResultSimplePublicObject" : {
        "required" : [ "completedAt", "startedAt", "status" ],
        "type" : "object",
        "properties" : {
          "completedAt" : {
            "type" : "string",
            "description" : "The date and time when the action was completed, in ISO 8601 format.",
            "format" : "date-time",
            "example" : null
          },
          "errors" : {
            "type" : "array",
            "description" : "An array of StandardError objects providing details about any errors that occurred.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/StandardError"
            }
          },
          "links" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "A map of link names to associated URIs, providing additional information or resources related to the action.",
            "example" : null
          },
          "numErrors" : {
            "type" : "integer",
            "description" : "An integer indicating the number of errors encountered during the action.",
            "format" : "int32",
            "example" : null
          },
          "requestedAt" : {
            "type" : "string",
            "description" : "The date and time when the action was requested, in ISO 8601 format.",
            "format" : "date-time",
            "example" : null
          },
          "result" : {
            "$ref" : "#/components/schemas/SimplePublicObject"
          },
          "startedAt" : {
            "type" : "string",
            "description" : "The date and time when the action started processing, in ISO 8601 format.",
            "format" : "date-time",
            "example" : null
          },
          "status" : {
            "type" : "string",
            "description" : "The current status of the action. Valid values include 'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'.",
            "example" : null,
            "enum" : [ "CANCELED", "COMPLETE", "PENDING", "PROCESSING" ]
          }
        },
        "example" : null
      },
      "AssociationPublicRequest" : {
        "required" : [ "to", "types" ],
        "type" : "object",
        "properties" : {
          "to" : {
            "$ref" : "#/components/schemas/AssociationToPublicRequest"
          },
          "types" : {
            "type" : "array",
            "description" : "An array of association types, each defined by the AssociationTypePublicRequest schema. This specifies the nature of the association between the objects.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/AssociationTypePublicRequest"
            }
          }
        },
        "example" : null
      },
      "AssociationToPublicRequest" : {
        "required" : [ "id" ],
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "The unique identifier for the target object. It is a required string property.",
            "example" : null
          },
          "objectType" : {
            "type" : "string",
            "description" : "The type of the target object. This is a string property that specifies the kind of object being associated.",
            "example" : null
          }
        },
        "example" : null
      },
      "AssociationTypePublicRequest" : {
        "required" : [ "associationCategory", "associationTypeId" ],
        "type" : "object",
        "properties" : {
          "associationCategory" : {
            "type" : "string",
            "description" : "A string representing the category of the association.",
            "example" : null
          },
          "associationTypeId" : {
            "type" : "string",
            "description" : "A string representing the unique identifier for the association type.",
            "example" : null
          }
        },
        "example" : null
      },
      "BillingAddress" : {
        "type" : "object",
        "properties" : {
          "city" : {
            "type" : "string",
            "description" : "The city of the billing address.",
            "example" : null
          },
          "country" : {
            "type" : "string",
            "description" : "The country of the billing address.",
            "example" : null
          },
          "line1" : {
            "type" : "string",
            "description" : "The first line of the billing address, typically containing the street address or PO Box number.",
            "example" : null
          },
          "line2" : {
            "type" : "string",
            "description" : "The second line of the billing address, often used for apartment, suite, or unit numbers.",
            "example" : null
          },
          "postalCode" : {
            "type" : "string",
            "description" : "The postal or ZIP code of the billing address.",
            "example" : null
          },
          "state" : {
            "type" : "string",
            "description" : "The state or region of the billing address.",
            "example" : null
          }
        },
        "example" : null
      },
      "CreateManualPaymentPublicRequest" : {
        "required" : [ "associations", "currencyCode", "paymentAmount", "paymentDate", "paymentMethod" ],
        "type" : "object",
        "properties" : {
          "associations" : {
            "type" : "array",
            "description" : "An array of associations related to the payment, where each item is an AssociationPublicRequest object.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/AssociationPublicRequest"
            }
          },
          "billingAddress" : {
            "$ref" : "#/components/schemas/BillingAddress"
          },
          "currencyCode" : {
            "type" : "string",
            "description" : "The currency code for the payment, represented as a string.",
            "example" : null
          },
          "customerEmail" : {
            "type" : "string",
            "description" : "The email address of the customer making the payment, represented as a string.",
            "example" : null
          },
          "paymentAmount" : {
            "type" : "number",
            "description" : "The amount of the payment, represented as a number.",
            "example" : null
          },
          "paymentDate" : {
            "type" : "string",
            "description" : "The date of the payment, represented as a string.",
            "example" : null
          },
          "paymentMethod" : {
            "type" : "string",
            "description" : "The method used for the payment, represented as a string.",
            "example" : null
          }
        },
        "example" : null
      },
      "CreateManualPaymentPublicResponse" : {
        "required" : [ "id" ],
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "The unique identifier for the created manual payment, represented as a string.",
            "example" : null
          }
        },
        "example" : null
      },
      "Error" : {
        "required" : [ "category", "correlationId", "message" ],
        "type" : "object",
        "properties" : {
          "category" : {
            "type" : "string",
            "description" : "The error category. Type: string.",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition. Type: object with additional properties of type array of strings.",
            "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. Type: string, Format: uuid.",
            "format" : "uuid",
            "example" : "aeb5f871-7f07-4993-9211-075dc63e7cbf"
          },
          "errors" : {
            "type" : "array",
            "description" : "Further information about the error. Type: 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. Type: object with additional properties of type string.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate. Type: string.",
            "example" : "An error occurred"
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error. Type: string.",
            "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.",
            "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 that are arrays of strings.",
            "example" : "{missingScopes=[scope1, scope2]}"
          },
          "in" : {
            "type" : "string",
            "description" : "The name of the field or parameter in which the error was found.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate.",
            "example" : null
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error.",
            "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
      },
      "PublicObjectWarning" : {
        "required" : [ "category", "context", "message" ],
        "type" : "object",
        "properties" : {
          "category" : {
            "type" : "string",
            "description" : "The category of the warning, represented as a string.",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "An object containing additional context about the warning, where each key-value pair provides further information.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A descriptive message providing details about the warning, represented as a string.",
            "example" : null
          }
        },
        "description" : "Represents a warning message related to a public object in HubSpot, providing details about the nature and context of the warning.",
        "example" : null
      },
      "SimplePublicObject" : {
        "required" : [ "archived", "createdAt", "id", "properties", "updatedAt" ],
        "type" : "object",
        "properties" : {
          "archived" : {
            "type" : "boolean",
            "description" : "A boolean indicating whether this object is archived.",
            "example" : null
          },
          "archivedAt" : {
            "type" : "string",
            "description" : "The date and time when this object was archived, in ISO 8601 format.",
            "format" : "date-time",
            "example" : null
          },
          "createdAt" : {
            "type" : "string",
            "description" : "The date and time when this object was created, in ISO 8601 format.",
            "format" : "date-time",
            "example" : null
          },
          "id" : {
            "type" : "string",
            "description" : "The unique identifier for this object, represented as a string.",
            "example" : null
          },
          "objectWriteTraceId" : {
            "type" : "string",
            "description" : "A string identifier used for tracing write operations on this object.",
            "example" : null
          },
          "properties" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "A map of property names to their current values, where each value is a string.",
            "example" : null
          },
          "propertiesWithHistory" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "$ref" : "#/components/schemas/ValueWithTimestamp"
              }
            },
            "description" : "A map of property names to arrays of historical values, each with a timestamp and source information.",
            "example" : null
          },
          "updatedAt" : {
            "type" : "string",
            "description" : "The date and time when this object was last updated, in ISO 8601 format.",
            "format" : "date-time",
            "example" : null
          },
          "url" : {
            "type" : "string",
            "description" : "A string representing the URL associated with this object.",
            "example" : null
          },
          "warnings" : {
            "type" : "array",
            "description" : "An array of warnings related to this object, with each warning containing a category, message, and context.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/PublicObjectWarning"
            }
          }
        },
        "description" : "A simple public object.",
        "example" : null
      },
      "StandardError" : {
        "required" : [ "category", "context", "errors", "links", "message", "status" ],
        "type" : "object",
        "properties" : {
          "category" : {
            "type" : "string",
            "description" : "A string indicating the category of the error.",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "An object containing additional context about the error condition, where keys are context names and values are arrays of strings.",
            "example" : null
          },
          "errors" : {
            "type" : "array",
            "description" : "An array of ErrorDetail objects providing further information about the error.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/ErrorDetail"
            }
          },
          "id" : {
            "type" : "string",
            "description" : "A string that uniquely identifies this specific error instance.",
            "example" : null
          },
          "links" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "An object mapping link names to associated URIs that contain documentation or recommended remediation steps for the error.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A string containing a human-readable message describing the error.",
            "example" : null
          },
          "status" : {
            "type" : "string",
            "description" : "A string representing the status of the error.",
            "example" : null
          },
          "subCategory" : {
            "type" : "object",
            "properties" : { },
            "description" : "An object providing more specific details about the error category.",
            "example" : null
          }
        },
        "description" : "Ye olde error",
        "example" : null
      },
      "TaskLocator" : {
        "required" : [ "id" ],
        "type" : "object",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "The unique identifier for the task, represented as a string.",
            "example" : null
          },
          "links" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "An object containing a map of link names to their associated URIs, represented as strings. These links provide additional information or actions related to the task.",
            "example" : null
          }
        },
        "example" : null
      },
      "ValueWithTimestamp" : {
        "required" : [ "sourceType", "timestamp", "value" ],
        "type" : "object",
        "properties" : {
          "sourceId" : {
            "type" : "string",
            "description" : "A string identifier for the specific source of the value.",
            "example" : null
          },
          "sourceLabel" : {
            "type" : "string",
            "description" : "A string label providing a human-readable description of the source.",
            "example" : null
          },
          "sourceType" : {
            "type" : "string",
            "description" : "A string indicating the type of source from which the value originated. This is a required field.",
            "example" : null
          },
          "timestamp" : {
            "type" : "string",
            "description" : "The date and time when the value was recorded, in ISO 8601 format.",
            "format" : "date-time",
            "example" : null
          },
          "updatedByUserId" : {
            "type" : "integer",
            "description" : "An integer representing the ID of the user who last updated the value.",
            "format" : "int32",
            "example" : null
          },
          "value" : {
            "type" : "string",
            "description" : "The value associated with the timestamp. It is a string representing the data at that point in time.",
            "example" : null
          }
        },
        "description" : "Property model that includes timestamp.",
        "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" : {
              "crm.objects.commercepayments.write" : "",
              "crm.schemas.commercepayments.write" : ""
            }
          }
        }
      },
      "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"
  }
}