Organization API: Organizations & Members: Referrals

Part of Organizations & Members.

GET /api/v1/orgs/{org_slug}/referrals

Every referral of the organization, newest first, and the program's totals.

Needs the Admin or Owner role. A referral is one referred customer: their first paid invoice started it. status is qualified while it waits out its hold (hold_until), credited once the wallet credit is paid, and void when a rule refused it (void_reason says which, or holds the reason staff gave). referrer and referee name the two customers, code the code that was used and invoice the invoice that started it. reward_amount is what the referrer is paid and referee_reward_amount the welcome credit, both in wallet dollars (currency). count is how many referrals match the filters. totals covers the whole program and ignores the filters: the number of referrals in each status, credited_amount paid out so far and owed_amount for the open ones.

GET /api/v1/orgs/{org_slug}/referrals/codes

The organization's referral codes, newest first, each with how many referrals it started.

Needs the Admin or Owner role. A customer code is made for each customer the first time they open their referral page. A partner code is made by your team and pays commission_bp of the referred customer's first invoice. referrals on a code is {total, credited, earned}: the referrals it started, how many were paid, and what they paid the owner in wallet dollars.

POST /api/v1/orgs/{org_slug}/referrals/codes

Make a partner code that pays a share of the first invoice of every customer it brings.

Needs the Admin or Owner role. Name the owner with customer_id or email: an active customer of this organization. commission_bp (1 to 5000, 100 is 1 percent) is the share of the referred customer's first invoice, without tax, paid into the owner's wallet once the hold has passed. code is optional: 3 to 40 letters, digits, hyphens or underscores, and without regard to capitals it must not be in use (409). Left out, we make an 8 character code. At most 30 codes an hour. Answers 422 with detail and field for a value that does not fit. The code is recorded in the audit log as referral_code.created.

application/json (required)

PATCH /api/v1/orgs/{org_slug}/referrals/codes/{code_id}

Change whether a code works, a partner code's commission, or its label. The code itself never changes.

Needs the Admin or Owner role. active: false stops the code from starting new referrals; referrals it already started still pay. commission_bp (1 to 5000) is for a partner code only: a customer's code pays the program's reward amount. label is a note for your team, and null or an empty string removes it. Send only what changes. Answers 404 for a code of another organization and 422 with detail and field for a value that does not fit. A change is recorded as referral_code.updated with the values before and after.

application/json (required)

GET /api/v1/orgs/{org_slug}/referrals/settings

The referral program's settings, with the wallet currency and the limit of each number.

Needs the Admin or Owner role. The program is off until enabled is true. reward_amount is paid to the customer who shared a code, referee_reward_amount to the customer who used it (0 for none), threshold_amount is what that customer's first paid invoice must reach without tax, hold_days how long a qualified referral waits before it is paid, monthly_cap how many referrals one customer is paid for in 30 days, and block_paid_ads whether an order that came from a paid ad is refused. Amounts are decimal strings in wallet dollars.

PUT /api/v1/orgs/{org_slug}/referrals/settings

Turn the program on or off and change its amounts, hold and limits.

Needs the Admin or Owner role. Send only the settings that change. reward_amount, referee_reward_amount and threshold_amount are amounts with at most 2 decimals (the first two 0 to 1000, the threshold 0 to 10000), hold_days is 1 to 90, monthly_cap is 1 to 500, enabled and block_paid_ads are true or false. A value that does not fit, or a name that is not a setting, answers 422 with detail, the sentence to show, and field, the input it belongs to, and changes nothing. The answer is the settings as GET gives them, with changed listing the keys that differ from before. A change is recorded in the audit log as referrals.settings_updated with the keys before and after. A new amount applies to referrals that start after the change. A referral already waiting keeps the amounts it started with.

application/json (required)

POST /api/v1/orgs/{org_slug}/referrals/{referral_id}/void

Void a referral so it is never paid. Only a pending or qualified referral can be voided.

Needs the Admin or Owner role. reason is required, 1 to 120 characters, and is kept as the referral's void_reason. A referral that is already credited or void answers 409, and money already paid is not taken back. Answers 404 for a referral of another organization. At most 60 an hour. Recorded in the audit log as referral.voided with the reason.

application/json (required)