Skip to main content
This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.
Use the payments API to create manual payment records for transactions collected outside of HubSpot, and to retry failed payments without requiring manual action in the HubSpot UI. Both endpoints are available to any account with HubSpot payments enabled.

Create a manual payment

To create a manual payment record, make a POST request to /commerce/payments/2027-03-beta/manual-payments. In the request body, you’ll need to include currencyCode, paymentAmount, paymentDate, and paymentMethod at a minimum.
When the request is successful, the response returns the id of the newly created payment record.

Associations

To associate the payment with other CRM records on creation, you can include the associations array in the create request body to define each association.
Supported associations for payments include:

Retry a failed payment

The retry endpoint uses an asynchronous pattern: you initiate the retry with a POST request, which returns a task ID, then poll a separate status endpoint to check the result.

Initiate a retry

To initiate a retry, make a POST request to /commerce/payments/2027-03-beta/{paymentCrmObjectId}/actions/retry/async, where {paymentCrmObjectId} is the ID of the payment CRM object you want to retry. A successful request returns a 202 response containing a TaskLocator object with the id of the retry task.

Check retry status

To check the status of a retry, make a GET request to /commerce/payments/2027-03-beta/{paymentCrmObjectId}/actions/retry/async/tasks/{taskId}/status, using the taskId value returned from the initiate request. The response includes a status field with one of the following values: The response also includes startedAt, completedAt, and, if any errors occurred, an errors array and numErrors count.
Last modified on November 16, 2026