v1

latestOpenAPI 3.0.12026-08-062532117.6 KB

Create a sale

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.

post/sales

Request body

referralIdstring

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.

emailstring email

Email of the customer. Also used to match an existing referral. Required unless referralId or promoCode is supplied.

promoCodestring

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.

namestring

Name of the customer. Required unless it can be taken from the matched referral.

totalEarnednumber float required

Gross value of the sale. Must be non-zero.

commissionRatenumber float

Overrides the affiliate's commission rate for this sale only. Defaults to the affiliate's own rate.

externalIdstring

The ID of this sale in your own system. Must be unique within the program.

externalInvoiceIdstring

The ID of the invoice in your own system. Must be unique within the program.

taxnumber float

Tax to deduct before commission is calculated. Only applied when your program has tax deduction enabled.

shippingnumber float

Shipping to deduct before commission is calculated. Only applied when your program has shipping deduction enabled.

Response

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

idinteger

The sale ID

affiliateIdstring uuid nullable

The affiliate credited with this sale

referralIdstring uuid nullable

The referral this sale belongs to

affiliateProgramIdstring uuid nullable

The affiliate program this sale belongs to

affiliateLinkIdstring uuid nullable

The affiliate link the sale was attributed to

promotionalCodeIdstring uuid nullable

The promotional code used on this sale, if any

externalIdstring nullable

The ID of this sale in your own system. Unique per program.

externalInvoiceIdstring nullable

The ID of the invoice in your own system. Unique per program.

namestring nullable

Name of the customer

emailstring email nullable

Email of the customer

totalEarnednumber float

Gross value of the sale

commissionRatenumber float nullable

Commission rate applied to this sale

commissionEarnednumber 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.

taxAmountnumber float

Tax deducted before commission was calculated

shippingAmountnumber float

Shipping deducted before commission was calculated

productsBoughtstring[]

Product identifiers attached to this sale

clicksinteger

Clicks attributed to this sale

status'ACTIVE' | 'REFUNDED'

Whether the sale is live or has been refunded

refundedAtstring date-time nullable

When the sale was marked refunded

paymentTrigger'SIGNUP' | 'PURCHASE' | 'BONUS' | 'CONTENT_REWARD'

What triggered the commission for this sale

Where the sale came from. Sales created through this API have API.

metadataobject nullable

Arbitrary JSON you can attach to the sale

createdAtstring date-time

When the sale was recorded