Payments
Use the payments API to fetch information about an account's payments. This is a read-only API, so it cannot be used for creating new or managing existing payments.
For example, use this API to fetch all refunded payments in an account.
To use this API, the account must be set up to collect payments through either HubSpot payments or Stripe payment processing.
Depending on the information you need, there are a few ways to retrieve payments:
- To retrieve all payments, make a
GET
request tocrm/v3/objects/commerce_payments
. - To retrieve a payment, make a
GET
request to the above URL and specify an payment ID. For example:crm/v3/objects/commerce_payments/44446244097
. - To retrieve payments that meet a specific set of criteria, you can make a
POST
request to the search endpoint and include filters in the request body. See an example of using the search endpoint below.
The response will include a few default properties, including the create date, last modified date.
To return specific properties, include a properties
query parameter in the request URL along with comma-separated property names. For example, making a GET
request to the following URL would result in the response below:
crm/v3/objects/commerce_payments?properties=hs_customer_email,hs_latest_status
To view all available payment properties, make a GET
request to crm/v3/properties/commerce_payments
. Learn more about using the properties API.
Below are some common payment properties that you may want to query.
Property name | Label in UI | Description |
---|---|---|
hs_latest_status |
The current status of the payment. Values include:
|
|
hs_initial_amount |
The total amount that the buyer was charged. |
|
hs_customer_email |
The buyer's email address. |
|
hs_initiated_date |
The date that the payment was created. |
|
hs_payment_id |
The payment's unique ID. |
You can use the search endpoint to retrieve payments that meet a specific set of filter criteria. This will be a POST
request that includes your filter criteria in the request body.
For example, to search for all refunded payments, you would make a POST
request to crm/v3/objects/commerce_payments/search
with the following request body:
Note that the filters
array specifies the search criteria, while the properties
array specifies which properties to return.
While you cannot set associations using this API, you can retrieve association information by making a GET request to the following URL:
crm/v3/objects/commerce_payments/{hs_object_id}/associations/{associatedObjectName}
Associated objects can include contacts, companies, deals, invoices, quotes, line items, subscriptions, discounts, fees, and taxes. These associates are based on the associations set on the invoice, payment link, or quote used for transaction. To manage these associations, you can update the payment in HubSpot.
Below is an example of how you might use this API combined with another API to get a specific set of association information.
Please note: when retrieving line items from different objects created in HubSpot, you should expect to receive different IDs. This is because line items should only be associated with one object, which HubSpot handles automatically by creating copies of line items rather than using the same line item across multiple objects.
To retrieve a payment and contact associated with it, make a GET
request to:
crm/v3/objects/commerce_payments/{hs_object_id}/associations/contact
This will return the IDs of the currently associated contact, along with meta information about the association type.
You can then use the returned IDs to request more information about the line items through the contacts API. For example, you could retrieve the contact using its ID by making a GET
request to crm/v3/objects/contacts/{contactId}
Thank you for your feedback, it means a lot to us.