GoFundMe Transaction Item API
Transaction Items describe the specific donations, tickets, registrations (and more) that could make up a Transaction. Some transactions will only have a single Transaction Item, but others may have many. Like transactions, transaction items have three types of attributes relating to Passport: raw, charged, and normalized. Raw attributes (e.g. `raw_currency_code`, `raw_final_price`, etc.) reflect donor intent through their donation or product purchases. `raw_final_price` represents the total raw value of a transaction item - it is either set directly (as with a direct donation) or derived from the product of `raw_price` (the price of the transaction item's associated product) and the specified quantity. Transaction items associated with a product may also have `raw_overhead_amount` set, which indicates the amount of the `raw_final_price` that is attributed to campaign overhead. All raw amounts are presented in terms of `raw_currency_code`, which is inherited from the transaction item's transaction and cannot be set on a per-item basis. Charged (e.g. `charged_final_price`, `charged_fees_amount`, etc.) attributes are all derived from the transaction item's associated transaction and reflect the percentage that the transaction item contributed to the transaction's raw gross amount. For example, a transaction item that contributed 85% of its transaction's `raw_total_gross_amount` through its `raw_final_price` will see its charged attributes reflect 85% of the transaction's charged attribute values. All of these values will be reflected in terms of the `charged_currency_code` of the transaction item's transaction. Normalized attributes (e.g. `final_price`, `fees_amount`, etc.) reflect a conversion from raw and/or charged attributes into the transaction item's `currency_code`, which is the same for all Passport-enabled entities associated with the transaction item's organization. This normalization occurs to allow for a constant basis of comparison across each of these entities. These normalized values are all converted from the associated raw or charged attributes, preferring the charged attribute over the raw attribute if available. For example, `charged_final_price` will be used instead of `raw_final_price` if both `charged_final_price` and `charged_currency_code` are present. If `charged_at` is also present, the exchange rate between `charged_currency_code` and `currency_code` at that time will be used if/when the transaction item is renormalized.
Documentation
Specifications
Other Resources
openapi: 3.2.0
info:
title: GoFundMe Pro Transaction Item API
description: "<h1>GoFundMe Pro API</h1>\n<p>Welcome to the GoFundMe Pro API (2.0.0), a powerful toolset that empowers innovative and creative minds to engineer the world for good. This documentation walks through the API’s latest endpoints.</p>\n<p>GoFundMe Pro APIs are crafted around REST and the REST architectural style to provide developers with a stateless and language-agnostic interface. The GoFundMe Pro API leverages HTTP verbs and response codes, OAuth2 authentication, and resource-oriented URLs.</p>\n<p>Currently, the GoFundMe Pro API only supports JSON. All POST/PUT requests required a valid JSON object for the request body.</p>\n<h2>Errors</h2>\n<p>The GoFundMe Pro API leverages standard HTTP response status codes for it’s error responses. Error codes are:</p>\n<p><br /></p>\n<table border='1'>\n<tr>\n<th width='100px'>Error Code</th>\n<th>Meaning</th>\n</tr>\n<tr>\n<td>400</td>\n<td>Bad Request: The request was malformed or provided incorrect/incomplete/conflicting parameters. Check the response for more detailed messaging about why the request was incorrect. Do not repeat request.</td>\n</tr>\n<tr>\n<td>401</td>\n<td>Unauthorized: The API does not recognize the request as authorized. API access token may be missing or invalid.</td>\n</tr>\n<tr>\n<td>403</td>\n<td>Forbidden: The API recognizes the authorized API user, but the API user does not have correct permissions to satisfy the request.</td>\n</tr>\n<tr>\n<td>404</td>\n<td>Not Found: The resource requested does not exist or was not found.</td>\n</tr>\n<tr>\n<td>405</td>\n<td>Method Not Allowed: Some REST endpoints only accept a subset of valid REST HTTP verbs. This error is sent when an unsupported verb is requested.</td>\n</tr>\n<tr>\n<td>429</td>\n<td>Too Many Requests: The rate limit has been exceeded. See the <a href=\"#rate-limiting\">Rate Limiting</a> section for details on rate limits and response headers.</td>\n</tr>\n<tr>\n<td>500</td>\n<td>Error: The request was valid, but something failed on the server. Additional messages may be available.</td>\n</tr>\n<tr>\n<td>503</td>\n<td>Service Unavailable: The service is temporarily unavailable.</td>\n</tr>\n</table>\n<h2>Requests</h2>\n<h3>Authenticating Requests</h3>\n<p>Most API requests will need to be signed with an Access Token.</p>\n<p>Refer to the <a href=\"https://developers.gofundme.com/pro/overview/authentication\" target=\"_blank\" rel=\"noopener noreferrer\">Resource Documentation</a> for the specific call you are making to see if an access token is required for your request. See <a href=\"https://developers.gofundme.com/pro/tutorials/samples\" target=\"_blank\" rel=\"noopener noreferrer\">this page</a> for a demonstration of usage through a sample app. \n<h3>Filters</h3>\n<p>We can filter a collection based on a set of input parameters. To do so, we can modify the query string using the parameters listed below.</p>\n\n<table border='1'>\n<tr>\n<th>Parameter</th>\n<th>Type</th>\n<th>Default</th>\n<th>Description</th>\n</tr>\n\n<tr>\n<td>with</td>\n<td>string</td>\n<td>N/A</td>\n<td>This allows you to include nested related resource. For example, you could request a campaign along with the organization it belongs to and the designation it was allocated to. In this case, <code>with=organization,designation.</code></td>\n</tr>\n\n<tr>\n<td>per_page</td>\n<td>integer</td>\n<td>20</td>\n<td>Set the total number of resources returned per page (Maximum: 100).</td>\n</tr>\n\n<tr>\n<td>page</td>\n<td>integer</td>\n<td>1</td>\n<td>Page to return.</td>\n</tr>\n\n<tr>\n<td>sort</td>\n<td>string</td>\n<td>Depends on endpoint</td>\n<td>\nOrder the resources depending upon their attributes. Examples:\n<ul>\n<li><strong>created_at</strong>: oldest resource will come first</li>\n<li><strong>created_at:desc</strong>: newest resource will come first</li>\n<li><strong>last_name:asc,first_name:asc</strong>: order resources by last_name in alphabetical order. If same last_name, order by first_name in alphabetical order.</li>\n</ul>\n</td>\n</tr>\n\n<tr>\n<td>fields</td>\n<td>string</td>\n<td>Depends on endpoint</td>\n<td>List of resources attributes separated with comma. Narrow the list of attributes returned for each resource.</td>\n</tr>\n\n<tr>\n<td>filter</td>\n<td>string</td>\n<td>NULL</td>\n<td>\nAllow to filter the list of resources returned. Format is: <code>{association}.{attribute1}{operand}{value}</code> where: <ul>\n<li>association is the association if this is a nested filter (optional)</li>\n<li>operand is one of the following: <code><=, >=, <>, !=, =, <, or ></code>. Operand must be url encoded. (Note: if you are filtering on a boolean value, <code>true</code> can be expressed with <code>true</code> or <code>1</code>. Additionally, false can be expressed with <code>false</code> or <code>0</code>).</li>\n<li>If filtering on an association, ensure you include the nested resource using the ‘with’ parameter. with | string | NULL | This allows you to include a nested related resource. For example, you could request a collection of campaigns along with the organization they belong to and the designation they were allocated to. In this case, <code>with=organization,designation</code>.</li>\n</ul>\n</td>\n</tr>\n</table>\n\n<p>When filtering, the operand should be one of the following:</p>\n<p><code><=, >=, <>, !=, =, <, or ></code>. Operand must be url encoded. (Note: if you are filtering on a boolean value, <code>true</code> can be expressed with <code>true</code> or <code>1</code>. Additionally, <code>false</code> can be expressed with <code>false</code> or <code>0</code>).</p>\n<p>If filtering on an association, ensure you include the nested resource using the ‘with’ parameter. This allows you to include a nested related resource. For example, you could request a collection of campaigns along with the organization they belong to and the designation they were allocated to. In this case, <code>with=organization,designation</code>.</p>\n<p>Refer to the sample documentation for the specific call you are making to see which related resource can be fetched.</p>\n\n<h3>Date and Time Filtering</h3>\n<p>Unless otherwise noted, all Datetime attributes in API responses will be returned in an ISO8601 compliant format:</p>\n<><code>YYYY-MM-DDTHH:mm:ss.sssZ</code> (e.g. <code>2024-10-05T14:48:00.000Z</code>).</p>\n<h2 id=\"rate-limiting\">Rate Limiting</h2>\n<p>The GoFundMe Pro API implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits are applied on a per-application and per-user basis.</p>\n<h3>When Rate Limiting Applies</h3>\n<p>Rate limiting is applied to requests that meet the following conditions:</p>\n<ul>\n<li>The API application is <strong>not internal</strong> (external/third-party applications)</li>\n<li>The API application is associated to an Organization</li>\n</ul>\n<p>Internal applications are not subject to rate limiting.</p>\n<h3>Rate Limit Details</h3>\n<p>By default, the rate limit is:</p>\n<ul>\n<li><strong>1800 requests per minute</strong> per application</li>\n</ul>\n<p>Rate limits may be adjusted dynamically via flags for specific applications or users.</p>\n<h3>Rate Limit Headers</h3>\n<p>All API responses include the following headers to help you track your rate limit status:</p>\n<table border='1'>\n<tr>\n<th width='200px'>Header</th>\n<th>Description</th>\n</tr>\n<tr>\n<td><code>X-RateLimit-Limit</code></td>\n<td>The maximum number of requests allowed in the current time window</td>\n</tr>\n<tr>\n<td><code>X-RateLimit-Remaining</code></td>\n<td>The number of requests remaining in the current time window</td>\n</tr>\n<tr>\n<td><code>X-RateLimit-Reset</code></td>\n<td>Unix timestamp indicating when the rate limit window resets (only included when limit is exceeded)</td>\n</tr>\n<tr>\n<td><code>Retry-After</code></td>\n<td>Number of seconds to wait before retrying (only included in 429 responses)</td>\n</tr>\n</table>\n<h3>Handling Rate Limit Errors</h3>\n<p>When you exceed the rate limit, the API will return a <code>429 Too Many Requests</code> response with the following structure:</p>\n<pre><code>{\n \"message\": \"Too Many Attempts.\",\n \"retry_after\": 42\n}</code></pre>\n<p>The response will include the <code>Retry-After</code> header indicating how many seconds you should wait before making another request.</p>\n<h3>Best Practices</h3>\n<ul>\n<li>Monitor the <code>X-RateLimit-Remaining</code> header to track your usage</li>\n<li>Implement exponential backoff when you receive a 429 response</li>\n<li>Respect the <code>Retry-After</code> header value before retrying</li>\n<li>Cache responses when possible to reduce API calls</li>\n<li>Batch operations when the API supports it</li>\n</ul>"
version: 2.0.0
servers:
- url: https://pro.gofundme.com/api/2.0
security:
- OAuth2Application: []
- OAuth2Member: []
tags:
- name: Transaction Item
description: "Transaction Items describe the specific donations, tickets, registrations (and more) that could make up a Transaction.\n Some transactions will only have a single Transaction Item, but others may have many.\n\nLike transactions, transaction items have three types of attributes relating to Passport: raw, charged, and normalized.\n\nRaw attributes (e.g. `raw_currency_code`, `raw_final_price`, etc.) reflect donor intent through their donation or product purchases. `raw_final_price` represents the total raw value of a transaction item - it is either set directly (as with a direct donation) or derived from the product of `raw_price` (the price of the transaction item's associated product) and the specified quantity. Transaction items associated with a product may also have `raw_overhead_amount` set, which indicates the amount of the `raw_final_price` that is attributed to campaign overhead. All raw amounts are presented in terms of `raw_currency_code`, which is inherited from the transaction item's transaction and cannot be set on a per-item basis.\n\nCharged (e.g. `charged_final_price`, `charged_fees_amount`, etc.) attributes are all derived from the transaction item's associated transaction and reflect the percentage that the transaction item contributed to the transaction's raw gross amount. For example, a transaction item that contributed 85% of its transaction's `raw_total_gross_amount` through its `raw_final_price` will see its charged attributes reflect 85% of the transaction's charged attribute values. All of these values will be reflected in terms of the `charged_currency_code` of the transaction item's transaction.\n\nNormalized attributes (e.g. `final_price`, `fees_amount`, etc.) reflect a conversion from raw and/or charged attributes into the transaction item's `currency_code`, which is the same for all Passport-enabled entities associated with the transaction item's organization. This normalization occurs to allow for a constant basis of comparison across each of these entities. These normalized values are all converted from the associated raw or charged attributes, preferring the charged attribute over the raw attribute if available. For example, `charged_final_price` will be used instead of `raw_final_price` if both `charged_final_price` and `charged_currency_code` are present. If `charged_at` is also present, the exchange rate between `charged_currency_code` and `currency_code` at that time will be used if/when the transaction item is renormalized.\n"
paths:
/transactions/{transaction}/items:
get:
tags:
- Transaction Item
summary: listTransactionItems
description: Fetch Transaction Items.
operationId: listTransactionItems
parameters:
- name: transaction
in: path
description: Primary identifier of Transaction
required: true
schema:
type: integer
example: 8734
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- properties:
data:
description: Collection of Transaction Item
type: array
items:
$ref: '#/components/schemas/TransactionItem'
first_page_url:
example: '{host}/transactions/{transaction_id}/items?page=1'
last_page_url:
example: '{host}/transactions/{transaction_id}/items?page=1'
path:
example: '{host}/transactions/{transaction_id}/items'
type: object
'403':
description: Requester is not authorized to perform action
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
'404':
description: Transaction not found
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundResponse'
/organizations/{organization}/transaction-items:
get:
tags:
- Transaction Item
summary: listOrganizationTransactionItems
description: Fetch Transaction Items for specific Organization.
operationId: listOrganizationTransactionItems
parameters:
- name: organization
in: path
description: Primary identifier of Organization
required: true
schema:
type: integer
example: 82364
- name: with
in: query
description: Request specific relationships to be returned with the Transaction Items
required: false
schema:
type: array
items:
type: string
enum:
- transaction
example: transaction
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- properties:
data:
description: Collection of Transaction Item
type: array
items:
$ref: '#/components/schemas/TransactionItem'
first_page_url:
example: '{host}/organizations/{organization}/transaction-items?page=1'
last_page_url:
example: '{host}/organizations/{organization}/transaction-items?page=1'
path:
example: '{host}/organizations/{organization}/transaction-items'
type: object
'403':
description: Requester is not authorized to perform action
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponse'
'404':
description: Organization not found
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundResponse'
components:
schemas:
TransactionItem:
title: Transaction Item
type: object
allOf:
- $ref: '#/components/schemas/TransactionItemFillable'
- properties:
campaign_id:
description: ID of Campaign the Transaction Item's Transaction is associated with
type: integer
example: 227362
donation_gross_amount:
description: Amount charged for item to shown
type: number
format: double
example: 0.89
donation_net_amount:
description: Amount charged for item
type: number
format: double
example: 0.89
fees_amount:
description: Fees charged for Transaction Item
type: number
format: double
example: 0.89
final_price:
description: Reflect a conversion from raw and/or charged attributes into the Transaction Item's `currency_code`, which is the same for all Passport-enabled entities associated with the Transaction item's Organization.
type: number
format: double
example: 0.89
fundraising_page_id:
description: ID of Fundraising Page the Transaction Item's Transaction is associated with
type:
- integer
- 'null'
example: 2173528
fundraising_team_id:
description: ID of Fundraising Team the Transaction Item's Transaction is associated with
type:
- integer
- 'null'
example: 209745
id:
description: Primary identifier of Transaction Item
type: integer
example: 17020
organization_id:
description: ID of Organization the Transaction Item's Transaction is associated with
type: integer
example: 82364
overhead_amount:
description: Amount of event/host fees
type: number
format: double
example: 25.5
price:
description: Price per unit
type: number
format: double
example: 12
product_id:
description: ID of the item's Product
type:
- integer
- 'null'
example: 73647
product_name:
description: Name of Product
type: string
example: Tickets
quantity:
description: Quantity purchased
type: integer
example: 2
transaction_id:
description: ID of Transaction the item belongs to
type: integer
example: 8734
commerce_order_item_id:
description: ID of Commerce Order Item the item belongs to
type:
- string
- 'null'
example: orit_8734
designation_id:
description: ID of the designation/project for the Commerce Order Item that the item belongs to
type:
- integer
- 'null'
example: 8734
type: object
PaginatedResponse:
title: Paginated Response
properties:
current_page:
description: Index of current page
type: integer
example: 1
data:
description: Collection of results
type: array
items:
type: object
first_page_url:
description: URL of first page of results
type:
- string
- 'null'
example: https://pro.gofundme.com/api/2.0/resource?page=1
from:
description: Index of first displayed result within total result set
type:
- integer
- 'null'
example: 1
last_page:
description: Index of last page in result set
type: integer
example: 1
last_page_url:
description: URL of last page of results
type:
- string
- 'null'
example: https://pro.gofundme.com/api/2.0/resource?page=1
next_page_url:
description: URL of next page of results
type:
- string
- 'null'
example: https://pro.gofundme.com/api/2.0/resource?page=2
path:
description: URL of current page of results
type:
- string
- 'null'
example: https://pro.gofundme.com/api/2.0/resource
per_page:
description: Maximum number of records returned per page of results
type: integer
example: 20
prev_page_url:
description: URL of previous page of results
type:
- string
- 'null'
example: https://pro.gofundme.com/api/2.0/resource?page=1
links:
description: Collection of objects representing pages {label, URL, active} that can be used to request the associated page of records.
type: array
items:
$ref: '#/components/schemas/PaginationLink'
to:
description: Index of last displayed result within total result set
type:
- integer
- 'null'
example: 1
total:
description: Total count of records in result set
type: integer
example: 1
type: object
ForbiddenResponse:
title: Forbidden Response
properties:
error:
description: Description of detected error in request
type: string
example: This action is unauthorized.
type: object
ResourceNotFoundResponse:
title: Resource Not Found Response
properties:
error:
description: Description of detected errors in request
type: string
type: object
TransactionItemFillable:
title: Transaction Item Fillable
properties:
product_name:
description: Name of product
type: string
maxLength: 64
example: Tickets
quantity:
description: Quantity purchased
type: integer
minimum: 1
example: 1
raw_final_price:
description: Represents the total raw value of a Transaction item - it is either set directly (as with a direct donation) or derived from the Product of `raw_price` (the price of the Transaction item's associated Product) and the specified quantity. All raw amounts are presented in terms of `raw_currency_code`, which is inherited from the Transaction item's Transaction and cannot be set on a per-item basis
type:
- number
- 'null'
format: double
minimum: 0
example: 15
raw_overhead_amount:
description: Which indicates the amount of the `raw_final_price` that is attributed to Campaign overhead.
type:
- number
- 'null'
format: double
minimum: 0
example: 15
type:
description: Type of Transaction Item ledger
type: string
enum:
- donation
- registration
- offline_donation
- chargeback_reversal
- custom_product
- auction
- good
example: donation
type: object
PaginationLink:
description: Object referencing a page for the resource queried that can be used to fetch that page.
properties:
label:
description: Identifier of the page.
type: string
example: '1'
url:
description: URL that can be used to fetch associated page of records.
type:
- string
- 'null'
example: '{host}/{resource}?page=1'
active:
description: Identifies whether the previously requested page matches the page this link object references.
type: boolean
example: true
type: object
parameters:
per_page:
name: per_page
in: query
description: Number of entries to return in each page of results
required: false
schema:
type: integer
example: 20
page:
name: page
in: query
description: Indicator of which page of results to return
required: false
schema:
type: integer
example: 1
securitySchemes:
OAuth2Application:
type: oauth2
description: OAuth bearer token for client application
flows:
clientCredentials:
tokenUrl: /oauth2/auth
refreshUrl: /oauth2/auth
scopes:
read: Read access
write: Write access
OAuth2Member:
type: oauth2
description: OAuth bearer token for client application with additional member context
flows:
password:
tokenUrl: /oauth2/auth
refreshUrl: /oauth2/auth
scopes:
read: Read access
write: Write access