Partner codes
Give every partner their own code, like SARAH20. A shopper who types it at checkout or in your app is crediting that partner in their own words, so the code works on any phone and any browser, whatever the person said about tracking. A link only works if the shopper taps it. A code works when they type it.
Turn codes on
Codes are a switch on each program.
- Set up Apex: Partner Network → Give partners codes. One switch per live program, plus what the code gives a shopper ("20% off your first month").
- MCP:
update_partner_program({ programId, couponCodesEnabled: true, couponDiscountLabel: "20% off your first month" })
Every active partner in that program gets a code the first time anyone looks at it: in their portal, on your partner list, or through list_partner_codes.
The code pattern
The pattern says what each code looks like. The default is {HANDLE}20, so @sarah gets SARAH20.
| Token | Becomes |
|---|---|
{HANDLE} | The partner's handle, in capitals |
{RANDOM} | Four random letters and numbers, for programs where handles are long or private |
Set it with couponCodePattern on update_partner_program. Codes already given out keep their text.
Where codes show up
- Your partner list shows each partner's code and how many times it was used, next to their handle.
- The partner's portal shows their code beside their link, with what it gives a shopper.
- MCP:
list_partner_codes({ programId })lists every partner's code and use count.
Make the discount in your checkout
The code has to give the shopper something.
- Stripe: make one coupon in Stripe for the discount (say, 20% off the first month). In Set up Apex → Partner Network → codes, pick that coupon under the program. Apex makes every partner's code in Stripe as a promotion code under it, now and as new partners join. Stripe codes take letters, numbers and dashes only, so a partner whose handle has an underscore gets a dash instead (
SARAH-K20). - Shopify: Discounts → Create discount → a code discount with the partner's code. Apex doesn't make Shopify discounts for you yet.
How a code pays the partner
| Where the code is used | What Apex does |
|---|---|
| Shopify checkout | The order arrives with the code. Apex pays the partner their commission on the order's subtotal (after discounts, before tax and shipping). Orders Apex catches up on later pay the same way. Test orders and old orders from a history import never pay. |
| Stripe payment | A payment that uses the code pays the partner. One that starts a subscription pays the program's subscription rate. If the person had no partner yet, the code makes them this partner's, so their renewals pay this partner too. |
| Typed in your app | The phone's install goes to that partner if nothing else brought it, and the person is remembered as the partner's for their later purchases. No money moves at that moment, because there is no sale yet. |
Each order pays once, however many times Apex hears about it.
Info
A code Apex made in Stripe is matched straight away. A code you made yourself needs Apex to read its text from Stripe. Shops connected with their own Stripe key are covered if the key can read promotion codes. Shops connected through Apex's Stripe app need the app's latest version, which asks to read coupons and promotion codes and to make promotion codes.
When a code and a link disagree
The person tapped @mike's link last month, then typed SARAH20 at checkout. Sarah gets this sale: the code is what the shopper said at the moment they paid. If the person had no partner yet, they become Sarah's. If they already belonged to Mike, they stay Mike's for future sales that don't use a code.
Codes typed in your app
With the Capacitor plugin 2.9.0 or later:
const result = await Apex.redeemCode({ code: input.value });
if (result) {
// result.code is the partner's code, result.discountLabel is what it gives.
// result.installCredited says whether this phone's install went to the partner.
}
redeemCode returns null for a code that isn't a partner's, so your app can fall back to its own codes. It waits for consent when you initialize with requireConsent.
A person who types a code and signs in later is still the partner's. Apex carries the code over when it learns who they are.
Related
- Getting started with Apex Mobile: the sign-in line that credits iPhone installs
- Programs + memberships
- Commission rules