---
title: "Create a sale"
method: POST
path: "/sales"
---

# Create a sale

`POST /sales`

Records a sale and pays out the resulting commission.

You must identify who the sale belongs to with one of `referralId`, `email` or `promoCode`. `referralId` is flexible: it accepts a referral UUID, an affiliate UUID, an affiliate link slug, or a numeric click ID. `email` matches an existing referral by email address.

`totalEarned` is required and must be non-zero. A customer `name` and `email` are also required — they are taken from the matched referral when you do not send them explicitly.

`commissionRate` overrides the affiliate's rate for this sale only. `tax` and `shipping` are deducted before commission is calculated, but only when your program has the matching deduction setting enabled.

When you pass `promoCode`, the code is validated for existence, active state, expiry and redemption limits, and its redemption counters are incremented on success.

## Request body

- NewSale
  - `referralId` string — Identifies who the sale belongs to. Accepts a referral UUID, an affiliate UUID, an affiliate link slug, or a numeric click ID. Required unless `email` or `promoCode` is supplied.
  - `email` string, email — Email of the customer. Also used to match an existing referral. Required unless `referralId` or `promoCode` is supplied.
  - `promoCode` string — A promotional code belonging to the affiliate to credit. Required unless `referralId` or `email` is supplied. Validated for existence, active state, expiry and redemption limits; its redemption counters are incremented on success.
  - `name` string — Name of the customer. Required unless it can be taken from the matched referral.
  - `totalEarned` number, float, required — Gross value of the sale. Must be non-zero.
  - `commissionRate` number, float — Overrides the affiliate's commission rate for this sale only. Defaults to the affiliate's own rate.
  - `externalId` string — The ID of this sale in your own system. Must be unique within the program.
  - `externalInvoiceId` string — The ID of the invoice in your own system. Must be unique within the program.
  - `product` Product
    - `productId` string — Product ID
    - `quantity` number — Quantity purchased
    - `price` number, float — Unit price at time of sale
    - `name` string — Product name
  - `tax` number, float — Tax to deduct before commission is calculated. Only applied when your program has tax deduction enabled.
  - `shipping` number, float — Shipping to deduct before commission is calculated. Only applied when your program has shipping deduction enabled.

## Response `200`

The recorded sale. Returns `null` when no affiliate could be resolved from the details supplied — check the response before assuming a commission was created.

- Sale
  - `id` integer — The sale ID
  - `affiliateId` string, uuid, nullable — The affiliate credited with this sale
  - `referralId` string, uuid, nullable — The referral this sale belongs to
  - `affiliateProgramId` string, uuid, nullable — The affiliate program this sale belongs to
  - `affiliateLinkId` string, uuid, nullable — The affiliate link the sale was attributed to
  - `promotionalCodeId` string, uuid, nullable — The promotional code used on this sale, if any
  - `externalId` string, nullable — The ID of this sale in your own system. Unique per program.
  - `externalInvoiceId` string, nullable — The ID of the invoice in your own system. Unique per program.
  - `name` string, nullable — Name of the customer
  - `email` string, email, nullable — Email of the customer
  - `totalEarned` number, float — Gross value of the sale
  - `commissionRate` number, float, nullable — Commission rate applied to this sale
  - `commissionEarned` number, float, nullable — Commission recorded for the credited affiliate. Merged in by the API from the sale's commission record — it is not a column on the sale itself.
  - `taxAmount` number, float — Tax deducted before commission was calculated
  - `shippingAmount` number, float — Shipping deducted before commission was calculated
  - `productsBought` string[] — Product identifiers attached to this sale
  - `clicks` integer — Clicks attributed to this sale
  - `status` 'ACTIVE' | 'REFUNDED' — Whether the sale is live or has been refunded
  - `refundedAt` string, date-time, nullable — When the sale was marked refunded
  - `paymentTrigger` 'SIGNUP' | 'PURCHASE' | 'BONUS' | 'CONTENT_REWARD' — What triggered the commission for this sale
  - `source` 'UNKNOWN' | 'API' | 'INTEGRATION' | 'MANUAL' | 'IMPORTED' | 'AUTOMATED' — Where the sale came from. Sales created through this API have `API`.
  - `metadata` object, nullable — Arbitrary JSON you can attach to the sale
  - `createdAt` string, date-time — When the sale was recorded

## Other responses

- `400` — None of `referralId` / `email` / `promoCode` was supplied; `totalEarned`, `name` or `email` is missing; the promo code was not found, is inactive, has expired, has hit its redemption limit, or has no affiliate attached; or the sale could not be created.
- `401` — The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid.
- `403` — API access is not enabled for this account.
- `404` — The affiliate program this token belongs to no longer exists.
- `429` — Too many requests for this token on this endpoint. Please slow down.

---

[API](https://skmtc.net/referly/apis/referly-api.md) · [All operations](https://skmtc.net/referly/apis/referly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/referly/referly-api/versions/0f506d61b9c3/schema)