> ## Documentation Index
> Fetch the complete documentation index at: https://developers.referly.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Sale

> Creates a new sale under the specified affiliate program. You must provide either a referralId, email, or promoCode to identify the affiliate and referral. When using a promo code, it will be validated for expiration, redemption limits, and active status.

Optional fields `tax` and `shipping` can be provided to exclude these amounts from the commission calculation. When the affiliate program has "Automatically deduct tax from commission calculation" or "Automatically deduct shipping from commission calculation" enabled, these amounts will be subtracted from the total before computing the affiliate's commission.


## OpenAPI

````yaml POST /sales
openapi: 3.0.1
info:
  title: Referly API
  description: API for managing affiliates, referrals, and sales for SaaS businesses
  version: 1.0.0
servers:
  - url: https://www.referly.so/api/v1
security:
  - bearerAuth: []
paths:
  /sales:
    post:
      summary: Create a new sale
      description: >-
        Creates a new sale under the specified affiliate program. You must
        provide either a referralId, email, or promoCode to identify the
        affiliate and referral. When using a promo code, it will be validated
        for expiration, redemption limits, and active status.
      requestBody:
        description: Sale details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewSale'
        required: true
      responses:
        '200':
          description: Sale created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sale'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NewSale:
      type: object
      required:
        - totalEarned
      properties:
        referralId:
          type: string
          format: uuid
          description: >-
            The referral ID, or affiliate link or affiliate ID associated with
            the sale (required if email and promoCode are not provided)
        email:
          type: string
          format: email
          description: >-
            Email associated with the sale (required if referralId and promoCode
            are not provided)
        promoCode:
          type: string
          description: >-
            The promotional code associated with an affiliate (required if
            referralId and email are not provided). When used, the promo code
            will be validated and its redemption count will be incremented.
        name:
          type: string
          description: Name of the customer (required if not found via referralId or email)
        externalId:
          type: string
          description: >-
            The external ID of the sale. This is the ID of the sale in the
            external system or your database.
        externalInvoiceId:
          type: string
          description: >-
            The external invoice ID of the sale. This is the ID of the invoice
            in the external system or your database (Useful if you invoice your
            customers when they purchase your product).
        totalEarned:
          type: number
          format: float
          description: Total amount earned from the sale
        commissionRate:
          type: number
          format: float
          description: >-
            Commission rate for the sale (optional, defaults to affiliate's
            commission rate)
        product:
          $ref: '#/components/schemas/Product'
          description: Product details for the sale
        tax:
          type: number
          format: float
          description: >-
            Optional tax amount to deduct from the commission calculation (when
            program has deduct tax enabled)
        shipping:
          type: number
          format: float
          description: >-
            Optional shipping amount to deduct from the commission calculation
            (when program has deduct shipping enabled)
    Sale:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: The sale ID
        affiliateId:
          type: string
          format: uuid
          description: The affiliate ID associated with the sale
        referralId:
          type: string
          format: uuid
          description: The referral ID associated with the sale
        externalId:
          type: string
          description: >-
            The external ID of the sale. This is the ID of the sale in the
            external system or your database.
        externalInvoiceId:
          type: string
          description: >-
            The external invoice ID of the sale. This is the ID of the invoice
            in the external system or your database (Useful if you invoice your
            customers when they purchase your product)
        name:
          type: string
          description: Name of the customer who made the sale
        email:
          type: string
          format: email
          description: Email associated with the sale
        totalEarned:
          type: number
          format: float
          description: Total amount earned from the sale
        commissionRate:
          type: number
          format: float
          description: Commission rate for the sale
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp of the sale
    Error:
      type: object
      properties:
        error:
          type: integer
          description: Error code
        message:
          type: string
          description: Error message
    Product:
      type: object
      properties:
        productId:
          type: string
          description: Product ID
        quantity:
          type: number
          description: Quantity purchased
        price:
          type: number
          format: float
          description: Unit price at time of sale
        name:
          type: string
          description: Product name
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````