> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstpromoter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tracking refunds and negative commissions
> The refund call is similar to the sale call. It works the same way, except that it generates negative commissions.**HTTP Request**
`POST https://firstpromoter.com/api/v1/track/refund`
## OpenAPI
````yaml openapi-tracking POST /refund
openapi: 3.0.1
info:
title: FirstPromoter Tracking API
description: >-
Our tracking API allows companies to track any type of signups, sales,
cancellations and refunds for any billing provider, you are not limited to
our built-in integrations with Stripe, Chargebee, Recurly and Braintree.
license:
name: MIT
version: 1.0.0
servers:
- url: https://firstpromoter.com/api/v1/track
security:
- apiKeyAuth: []
paths:
/refund:
post:
description: ' The refund call is similar to the sale call. It works the same way, except that it generates negative commissions.**HTTP Request**
`POST https://firstpromoter.com/api/v1/track/refund`'
parameters:
- name: email
in: query
description: |-
`required if uid is null`
Email of the lead/sign-up
schema:
type: string
- name: uid
in: query
description: |-
`required if email is null`
uid of the lead added on signup tracking
schema:
type: string
- name: event_id
in: query
required: true
description: >-
Transaction or refund event ID. It's required to avoid generating
duplicate refunds in case you mistakenly send the same API call
multiple times.
schema:
type: string
- name: amount
in: query
required: true
description: >-
The refund amount in cents. It's used to calculate the negative
commissions/rewards.
schema:
type: string
- name: currency
in: query
description: >-
This field is only required if the currency of the sale/refund is
not the same as the one set on FirstPromoter settings. We'll
automatically convert the amount from this currency to the default
one set on your FirstPromoter account.
schema:
type: string
- name: quantity
in: query
description: >-
Number of subscriptions/items refunded. If it's only one, you can
skip this parameter.
schema:
type: string
- name: sale_event_id
in: query
description: >-
The event id of the sale for which the refund is processed. This
value must match the event_id value sent in the sale tracking API
call. (Note: This field is marked as optional, but if you track
multiple products or change the commission level often, it becomes
required to track refunds correctly)
schema:
type: string
- name: skip_email_notification
in: query
description: Set this to `true` to skip email notifications. Default is `false`.
schema:
type: boolean
- name: created_at
in: query
description: ISO 8601 date string of when the refund occurred. Defaults to now.
schema:
type: string
format: date-time
- name: ecom_refund
in: query
description: Set to `true` for e-commerce refunds (non-subscription).
schema:
type: boolean
responses:
'200':
description: Success response
content:
application/json:
schema:
type: object
properties:
id:
type: integer
example: 33847726
type:
type: string
example: refund
amount_cents:
type: integer
example: -1000
reward:
type: object
properties:
id:
type: integer
example: 10940148
status:
type: string
example: approved
amount:
type: integer
example: -200
unit:
type: string
example: cash
created_at:
type: string
format: date-time
example: '2024-09-11T14:36:01.016Z'
lead:
$ref: '#/components/schemas/Lead'
event_id:
type: string
example: test_sale_12340987_refund
conversion_amount:
type: integer
example: -1000
tier_level:
type: integer
example: 1
split_type:
type: string
nullable: true
example: null
lead:
$ref: '#/components/schemas/Lead'
promoter:
$ref: '#/components/schemas/Promoter'
'204':
description: No Content
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Error. Amount blank or invalid.
'409':
description: Conflict
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: >-
The 'refund' event with the id 'test_sale_12340987_refund'
already exists.
components:
schemas:
Lead:
type: object
properties:
id:
type: integer
example: 20738339
state:
type: string
example: cancelled
email:
type: string
example: hello@testmintli.com
uid:
type: string
nullable: true
example: null
customer_since:
type: string
format: date-time
example: '2024-09-11T14:22:12.160Z'
cancelled_at:
type: string
format: date-time
example: '2024-09-11T15:07:46.174Z'
plan_name:
type: string
nullable: true
example: null
suspicion:
type: string
example: no_suspicion
username:
type: string
nullable: true
example: null
website:
type: string
nullable: true
example: null
created_at:
type: string
format: date-time
example: '2024-09-09T16:22:44.168Z'
split_promotion_id:
type: string
nullable: true
example: null
custom_fields:
type: string
nullable: true
example: null
split_percentage_value:
type: string
nullable: true
example: null
visitor_sub_id:
type: string
nullable: true
example: null
Promoter:
type: object
properties:
id:
type: integer
description: ID of the promoter
example: 3920164
status:
type: string
description: Status of the promoter
example: active
cust_id:
type: string
example: ''
email:
type: string
description: Email of the promoter
example: peluwydo@mailinator.com
created_at:
type: string
format: date-time
description: ISO date of when the promoter was created
example: '2022-04-26T15:28:24.800Z'
temp_password:
type: string
description: Temporary password created for the promoter
nullable: true
example: xxxxxxxxxx
default_promotion_id:
type: integer
example: 4210919
pref:
type: string
example: db1znwe
default_ref_id:
type: string
description: Default referral id of the promoter
example: 8yi2epelut
note:
type: string
description: A note/description of promoter
nullable: true
example: This is a note
w8_form_url:
type: string
description: Url of the w8 form
nullable: true
example: null
w9_form_url:
type: string
description: Url of the w9 form
nullable: true
example: null
parent_promoter_id:
type: integer
description: Parent promoter id
example: 577918
earnings_balance:
type: object
description: Earning balance of the promoter
properties:
cash:
type: integer
example: 50744
current_balance:
type: object
description: Current balance of the promoter
properties:
cash:
type: integer
example: 20044
paid_balance:
type: object
description: Paid balance of the promoter
properties:
cash:
type: integer
example: 30700
auth_token:
type: string
description: Authentication token generated when the promoter was created
example: xxxxxxxxxxxxxx
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````