> ## 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

> Record a refund for a referred customer so FirstPromoter generates the matching negative commission (legacy v1 API).

The refund call is similar to the sale call. It works the same way, except that it generates negative commissions.


## 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.<Tip>**HTTP Request** <br/>`POST https://firstpromoter.com/api/v1/track/refund`</Tip>'
      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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.