← All docs

The merchant API

Everything the app shows you about your affiliate program, readable from your own code, plus the handful of decisions worth automating. It is a plain HTTPS API: one header, JSON in, JSON out, no SDK to install and nothing to sign.

The base URL is https://app.sproutaffiliate.com, and every path below hangs off /api/v1/.

What it is for

Three jobs, roughly. Getting your affiliate figures into somewhere else you already look, a warehouse, a Google Sheet, an internal dashboard. Keeping another system in step, a CRM that should know who your affiliates are and what they have earned. And automating a decision you currently make by hand, most often approving referral orders that meet a rule of your own.

It is a merchant API. Every call is made by you, about your own store, with a key you created. There is nothing here for an affiliate: affiliates have their portal and their own app, and neither goes through this.

A few things the API deliberately does not do. It cannot create or edit a program, because programs are built in the admin where the plan gates, the product pickers, and the discount rewrites live, and a program written from outside those is a program the admin would refuse to save. It cannot create an affiliate: people join through your signup page. It cannot change how an affiliate is paid: the payout method is theirs, set by them in their portal. And it does not hand out an affiliate’s stored payout details, the PayPal address, bank account, or postal address they entered in their own portal. The affiliate endpoints tell you only whether an account is on file. The one place a destination does appear is a payout you already made, where it is a record of your own payment rather than a lookup of their details.

Creating a key

Creating a key needs the Professional plan. Below it the API keys card shows the plan name and the Create key button is off, but nothing is taken away: keys already on the store stay listed, and you can still revoke one.

1. Open Sprout Affiliate in your Shopify admin, then Settings in the left menu.
2. Along the top of the Settings page, click the Developer tab.
3. In the API keys card, type a name that says what will be using it, "Warehouse sync" or "Zapier", not "key 2". A leaked key has to be findable, and the name is what you will be looking at.
4. Set Access to Read only or Read and write. Pick Read only unless the thing you are building actually needs to change something.
5. Click Create key.
6. Copy the secret. It looks like sk_sprout_ followed by 32 characters.

The list shows each key's name, its prefix, its scope, when you made it, and when it was last used. Last used is stamped at most once a minute, so it answers "is anything still calling with this" without a database write on every request. Check it before you revoke something.

Revoking is immediate and permanent. The next call with that key gets a 401. Revoked keys are kept rather than deleted, because an audit of what happened has to be able to name the key that did it.

Make one key per integration. They are free, and the point of separating them is that you can kill one without taking down the others, and the per-key rate limit means one integration going wrong cannot lock the rest out.

Authenticating

One header, on every request:

Authorization: Bearer sk_sprout_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The examples below assume you have put the key in your shell:

export SPROUT_KEY=sk_sprout_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Nothing else authenticates. No shop parameter, no signature, no OAuth dance. A missing header, a header that is not a Bearer token, or a token that does not start with sk_sprout_ is a 401 before anything is looked up.

A revoked key and a key that never existed return the same message, "Invalid API key.", on purpose: the endpoint must not be usable to find out which keys a store ever had.

The response envelope

Every reply from every endpoint, success or failure, is JSON in one of two shapes. There is no third.

Success

{ "ok": true, "data": { ... } }

Failure

{ "ok": false, "error": "This key is read only." }

So ok is the only thing you have to branch on, and error is always a sentence, not a code you have to look up. The HTTP status carries the same verdict: any 2xx has data, anything else has error.

The content type is always application/json; charset=utf-8. Endpoints that only read refuse other methods inside the envelope too, so a POST where a GET belongs gets a 405 with an error string. A path no endpoint answers on gets a 404 in the same envelope. Nothing under /api/v1/ can hand you an HTML page or a third shape, whatever you send it.

Money is a plain number, rounded to cents, in your store's payout currency, unconverted. Every response that carries an amount also carries the currency it is in, so you never have to assume. Dates are YYYY-MM-DD in your shop's timezone, the same calendar day the admin shows for the same row: an evening sale in a store behind UTC is that day's sale, not tomorrow's.

Read keys and write keys

A key is one or the other, chosen when you create it and not changeable afterwards. To change a key's scope, revoke it and make a new one.

Eleven calls need a write key, and nine of them touch money or who gets it:

• POST /api/v1/payouts runs a payout. In paypal mode it sends real money immediately, and nobody can undo it.
• POST /api/v1/orders/:id/approve moves a referral into the payable queue, which is what the next payout run pays.
• POST /api/v1/orders/:id/reject takes a commission off an affiliate, and credits the usage fee you were charged on that sale back (2% on Growth, 1.5% on Professional, 1% on Enterprise).
• POST /api/v1/bonuses creates a debt your store owes, which the next payout run sends.
• POST /api/v1/deductions takes an amount off what the next payout run sends.
• POST /api/v1/events records a custom event, which earns the affiliate the amount the program pays for it.
• PATCH /api/v1/affiliates changes up to 250 affiliates at once: their rate, status, or note.
• PATCH /api/v1/affiliates/:ref changes one affiliate's rate, status, or note. The rate is money: it is what every referral of theirs from that moment on is calculated at.
• POST /api/v1/affiliates/:ref/approve approves an application, which is what lets that person start earning.
• POST /api/v1/affiliates/:ref/reject declines one.
• PATCH /api/v1/payouts/schedule changes when automatic payouts run, or turns them off.

The other two, POST /api/v1/hooks and DELETE /api/v1/hooks/:id, add and remove webhook endpoints.

Each of those says so again in its own section. If what you are building only reads, use a read key and the question never comes up.

The rate limit

120 requests a minute, per key. Go over it and you get a 429 with "Too many requests. The limit is 120 a minute."

Per key rather than per store, deliberately. One integration in a retry loop must not lock a merchant out of their own other integrations, so a runaway key exhausts its own allowance and nothing else's. That is also the practical argument for a key per integration.

The window is a fixed sixty seconds that starts on your first request, not a rolling one. There is no Retry-After header and no remaining-quota header; wait a minute and carry on. If you are paging a large list, a small pause between pages is plenty: 120 a minute is well above what an honest sync needs.

Errors

Every failure is the same envelope with a sentence in error. The statuses you will actually meet:

Every endpoint

Twenty-three calls across sixteen paths. That is the whole surface.

GET /api/v1/shop read

The credentials check, and the call to make first. It tells you which store the key in your hand actually reaches, what that key may do, and the currency and timezone every other figure in this API is expressed in. No parameters.

Request

curl -s https://app.sproutaffiliate.com/api/v1/shop \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "shop": "kodak-supply.myshopify.com",
    "name": "Kodak Supply",
    "storefrontDomain": "kodaksupply.com",
    "plan": "Growth",
    "currency": "USD",
    "timezone": "America/New_York",
    "country": "US",
    "key": { "id": "cm4q8x2v70001l908h3fz2k1p", "scope": "read" }
  }
}

GET /api/v1/affiliates read

Your affiliates, oldest first, by the day they joined. Two people who joined on the same day hold a fixed order between them, so a page boundary falls in the same place every time you page.

Request

curl -s "https://app.sproutaffiliate.com/api/v1/affiliates?status=active&limit=2" \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "affiliates": [
      {
        "ref": "k7m2p9xd",
        "name": "Sarah Chen",
        "email": "sarah@example.com",
        "status": "active",
        "program": "creators",
        "code": "SARAH10",
        "rate": 12,
        "payoutMethod": "paypal",
        "createdAt": "2026-03-14"
      },
      {
        "ref": "nicklaus",
        "name": "Nicklaus Reed",
        "email": "nick@example.com",
        "status": "active",
        "program": "creators",
        "code": null,
        "rate": 10,
        "payoutMethod": "store-credit",
        "createdAt": "2026-05-02"
      }
    ],
    "count": 2,
    "total": 38,
    "byStatus": { "unverified": 1, "pending": 4, "active": 38, "inactive": 3 },
    "hasMore": true,
    "nextCursor": "MjAyNi0wNS0wMiBjbTRxOHgydjcwMDAybDkwOGYyYnE0dzhu"
  }
}

cursor=""
while :; do
  page=$(curl -s "https://app.sproutaffiliate.com/api/v1/affiliates?limit=250&cursor=$cursor" \
    -H "Authorization: Bearer $SPROUT_KEY")
  echo "$page" | jq -c '.data.affiliates[]'
  cursor=$(echo "$page" | jq -r '.data.nextCursor // empty')
  [ -z "$cursor" ] && break
done

GET /api/v1/affiliates/:ref read

One affiliate, plus the four money figures their own page in the admin shows for them, plus any bonus they are owed.

:ref is the link name. A ref that has since been renamed still resolves, to whoever moved away from it, so an integrator that stored the old name is not broken by you renaming someone. A ref that is currently somebody's live link name always wins over an alias.

Request

curl -s https://app.sproutaffiliate.com/api/v1/affiliates/k7m2p9xd \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "affiliate": {
      "ref": "k7m2p9xd",
      "name": "Sarah Chen",
      "email": "sarah@example.com",
      "status": "active",
      "program": "creators",
      "programName": "Creators",
      "code": "SARAH10",
      "rate": 12,
      "payoutMethod": "paypal",
      "payoutSet": true,
      "note": "Introduced by Nicklaus. Ships her own samples.",
      "createdAt": "2026-03-14"
    },
    "royalty": {
      "rate": 5,
      "amountPerItem": null,
      "products": [
        { "id": "gid://shopify/Collection/4417", "type": "collection", "title": "Sarah's capsule line", "since": "2026-09-01T00:00:00.000Z" }
      ]
    },
    "currency": "USD",
    "ordersAvailable": true,
    "totals": {
      "pending": 84.5,
      "approved": 212.4,
      "paid": 1940.15,
      "imported": 610,
      "unpaidBonuses": 50
    },
    "bonuses": [
      { "id": "cm4qa1p3k0007l908d5yv8w2r", "amount": 50, "note": "Best April post" }
    ]
  }
}

The affiliate object is the same field names the list endpoint returns for the same things, so a client can read a row from either one, with three additions: programName (the program's display name), payoutSet (whether there is an account on file to pay, without returning the account), and note (your private note, which the affiliate never sees).

Beside it, this endpoint returns one setting from the affiliate's page (see Royalties):

PATCH /api/v1/affiliates/:ref write

Change one affiliate. Send a JSON object with only the fields you want changed; anything you leave out is left exactly as it was. At least one recognised field is required, or you get a 400 Nothing to change.

Request

curl -s -X PATCH https://app.sproutaffiliate.com/api/v1/affiliates/k7m2p9xd \
  -H "Authorization: Bearer $SPROUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rate": 15, "note": "Bumped for Q3 campaign."}'

Response

{
  "ok": true,
  "data": {
    "changed": ["rate", "note"],
    "affiliate": {
      "ref": "k7m2p9xd",
      "name": "Sarah Chen",
      "email": "sarah@example.com",
      "status": "active",
      "program": "creators",
      "programName": "Creators",
      "code": "SARAH10",
      "rate": 15,
      "payoutMethod": "paypal",
      "payoutSet": true,
      "note": "Bumped for Q3 campaign.",
      "createdAt": "2026-03-14"
    }
  }
}

changed lists only what actually moved. Setting a field to the value it already had is not a change and will not appear, so a request whose every field already matched returns 400 Nothing to change. rather than a silent no-op. The affiliate object is the row as it now stands.

Three refusals worth planning for:

• 409 Approve their application first, with POST /api/v1/affiliates/:ref/approve. The affiliate is still pending or unverified. A pending application is approved with POST /api/v1/affiliates/:ref/approve; an unverified signup has not confirmed their email yet and cannot be approved until they do.
• 400 A rate has to be between 0 and 100. The rate is a percentage, not a fraction: send 15, not 0.15.
• 400 A payout method can only be set by the affiliate, in their portal. It is read only here. The body carried payoutMethod or payoutDetails. Refused out loud rather than ignored, so nobody goes away believing an affiliate's payouts were rerouted.

POST /api/v1/affiliates/:ref/approve write

Approve an affiliate whose status is pending: somebody who applied and is waiting on you. It does exactly what Approve does in the app. The affiliate becomes active, the discount code your program and plan call for is created in your Shopify, and they are emailed that they are in. There is no body.

Only a pending application can be approved. Anybody else answers 404 with "Application not found."; an active affiliate is changed with PATCH instead. An applicant whose program has since been deleted is refused with 400 and a message saying to move them to a program first, because there is no discount to put on their code.

Request

curl -s -X POST https://app.sproutaffiliate.com/api/v1/affiliates/k7m2p9xd/approve \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": { "ref": "k7m2p9xd", "status": "active", "code": "SARAH10" }
}

code is the discount code that was created, or null when the program gives out none.

POST /api/v1/affiliates/:ref/reject write

Decline a pending application. The application is removed and the applicant is emailed that it was declined, the same as Decline in the app. This cannot be undone: they would have to apply again. There is no body, and anybody who is not a pending applicant answers 404.

Request

curl -s -X POST https://app.sproutaffiliate.com/api/v1/affiliates/k7m2p9xd/reject \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{ "ok": true, "data": { "ref": "k7m2p9xd", "status": "declined" } }

GET /api/v1/programs read

Every program, with its commission setup, its customer discount setup, and its all-time totals. Read only: programs are created and edited in the admin.

Request

curl -s "https://app.sproutaffiliate.com/api/v1/programs?slug=creators" \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "programs": [
      {
        "slug": "creators",
        "name": "Creators",
        "active": true,
        "startDate": "2026-10-12",
        "endDate": null,
        "status": "open",
        "isDefault": true,
        "isReferral": false,
        "cookieDays": 30,
        "cookieHours": null,
        "stopAfterPurchase": false,
        "commission": {
          "type": "percent",
          "rate": 10,
          "flatAmount": 0,
          "tiers": null,
          "tierBasis": null,
          "tierReset": null,
          "cycleEvery": null,
          "resetDate": null,
          "resetWeekday": null,
          "resetMonthday": null,
          "resetTime": null,
          "productScope": "all",
          "products": [],
          "productRates": [],
          "typeLabel": "Percent of sale",
          "amountLabel": "10%",
          "firstOrderOnly": false,
          "renewalMonths": null,
          "orderRules": [
            { "field": "tag", "values": ["vip"], "rate": 15 },
            { "field": "email", "values": ["@brightside.example"], "rate": 5 }
          ],
          "clickSplit": { "first": 40, "last": 40 }
        },
        "eventTypes": [
          { "key": "booked_call", "name": "Booked call", "amount": 25, "dailyCap": 2 }
        ],
        "discount": {
          "mode": "code",
          "percent": 10,
          "scope": "all",
          "products": [],
          "usageLimit": 0,
          "oncePerCustomer": false,
          "requiresApproval": false
        },
        "payoutMethods": ["paypal", "store-credit"],
        "stats": {
          "affiliates": 24,
          "referralOrders": 391,
          "salesDriven": 28104.6
        }
      }
    ],
    "count": 1,
    "currency": "USD",
    "defaultProgram": "creators",
    "unpaidOrdersIncluded": true
  }
}

GET /api/v1/orders read

Every referral order on the store with your decision on each, newest first. This is the list that grows forever, so it is the one with a cursor.

Request

curl -s "https://app.sproutaffiliate.com/api/v1/orders?status=pending&limit=1" \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "currency": "USD",
    "orders": [
      {
        "orderId": "gid://shopify/Order/5512847360101",
        "order": "#1842",
        "date": "2026-08-24",
        "createdAt": "2026-08-24T19:41:08Z",
        "affiliateRef": "k7m2p9xd",
        "affiliateName": "Sarah Chen",
        "customer": "Dana Whitfield",
        "sale": 168,
        "commission": 20.16,
        "status": "pending",
        "holdReason": "",
        "paidAt": null,
        "part": "order",
        "splitByClicks": false
      }
    ],
    "count": 1,
    "total": 6,
    "totals": {
      "pending": { "orders": 6, "sales": 1043.5, "commission": 125.22 },
      "approved": { "orders": 11, "sales": 1802, "commission": 216.24 },
      "paid": { "orders": 140, "sales": 23114.75, "commission": 2773.77 },
      "rejected": { "orders": 2, "sales": 310, "commission": 37.2 }
    },
    "hasMore": true,
    "nextCursor": "MjAyNi0wOC0yNFQxOTo0MTowOFogZ2lkOi8vc2hvcGlmeS9PcmRlci81NTEyODQ3MzYwMTAx"
  }
}

To read the whole list, loop until nextCursor is null. It is null on the last page precisely so you can loop on that instead of comparing counts.

cursor=""
while :; do
  page=$(curl -s "https://app.sproutaffiliate.com/api/v1/orders?limit=250&cursor=$cursor" \
    -H "Authorization: Bearer $SPROUT_KEY")
  echo "$page" | jq -c '.data.orders[]'
  cursor=$(echo "$page" | jq -r '.data.nextCursor // empty')
  [ -z "$cursor" ] && break
done

POST /api/v1/orders/:id/approve write

:id is the orderId from GET /api/v1/orders. A plain Shopify order number is accepted too, as long as it names exactly one referral row; when it matches more than one you get a 409 asking for the full id, because guessing which row was meant would move the wrong commission.

Only a pending order can be approved. There is no body.

Request

curl -s -X POST \
  "https://app.sproutaffiliate.com/api/v1/orders/gid%3A%2F%2Fshopify%2FOrder%2F5512847360101/approve" \
  -H "Authorization: Bearer $SPROUT_KEY"

The order id contains slashes, so URL-encode it. A plain order number needs no encoding:

curl -s -X POST https://app.sproutaffiliate.com/api/v1/orders/1842/approve \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "order": {
      "orderId": "gid://shopify/Order/5512847360101",
      "order": "#1842",
      "affiliateRef": "k7m2p9xd",
      "affiliateName": "Sarah Chen",
      "commission": 20.16,
      "sale": 168,
      "status": "approved"
    }
  }
}

POST /api/v1/orders/:id/reject write

Identical to approve in every other respect: same :id, same "pending only" rule, no body, same refusals. Only a pending order can be rejected, and a paid one especially cannot: the affiliate already has the money, but the rejection would credit the fee back anyway.

Request

curl -s -X POST https://app.sproutaffiliate.com/api/v1/orders/1842/reject \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "order": {
      "orderId": "gid://shopify/Order/5512847360101",
      "order": "#1842",
      "affiliateRef": "k7m2p9xd",
      "affiliateName": "Sarah Chen",
      "commission": 20.16,
      "sale": 168,
      "status": "rejected"
    }
  }
}

{
  "ok": true,
  "data": {
    "order": { "...": "..." },
    "warning": "Rejected, but crediting the 2% fee on it didn't go through. Check billing, or restore and reject it again."
  }
}

GET /api/v1/bonuses read

Unpaid bonuses, oldest first. Once a payout run pays one it leaves this list and turns up in that affiliate's ledger instead, so this is a list of what you still owe outside commission. Deductions are not listed here; they have their own list.

Request

curl -s https://app.sproutaffiliate.com/api/v1/bonuses \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "bonuses": [
      {
        "id": "cm4qa1p3k0007l908d5yv8w2r",
        "ref": "k7m2p9xd",
        "name": "Sarah Chen",
        "amount": 50,
        "note": "Best April post"
      },
      {
        "id": "cm4qb7t2m0009l908k1qz4n6h",
        "ref": "nicklaus",
        "name": "Nicklaus Reed",
        "amount": 25,
        "note": ""
      }
    ],
    "count": 2,
    "matched": 2,
    "total": 75,
    "currency": "USD"
  }
}

count is what this page returned. matched and total cover every unpaid bonus the filter selects, not just this page, so a truncated page can never understate what your store owes. name is null when the affiliate has since been deleted: the debt outlives them.

POST /api/v1/bonuses write

Request

curl -s -X POST https://app.sproutaffiliate.com/api/v1/bonuses \
  -H "Authorization: Bearer $SPROUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "k7m2p9xd", "amount": 50, "note": "Best April post"}'

Response, 201 Created

{
  "ok": true,
  "data": {
    "bonus": {
      "id": "cm4qa1p3k0007l908d5yv8w2r",
      "ref": "k7m2p9xd",
      "amount": 50,
      "note": "Best April post"
    },
    "currency": "USD"
  }
}

GET /api/v1/events read

The custom events you reported, newest first, each with whether a payout has paid it. A custom event is an action Sprout Affiliate cannot see on its own, reported by your own system: see POST /api/v1/events.

{
  "ok": true,
  "data": {
    "events": [
      {
        "externalId": "calendly-8812",
        "entryId": "event:3f9c0a1b2d4e5f6a7b8c9d0e",
        "type": "booked_call",
        "name": "Booked call",
        "ref": "maya",
        "amount": 25,
        "occurredAt": "2026-10-06T14:30:00.000Z",
        "recordedAt": "2026-10-06T14:30:04.112Z",
        "note": "Intro call",
        "paid": false
      }
    ],
    "count": 1,
    "currency": "USD"
  }
}

amount and name are what the event earned when it was recorded. Editing or removing the event type in the program afterward never changes an event already recorded. type is the key the type has now, and "" once the type was removed.

POST /api/v1/events write

Request

curl -s -X POST https://app.sproutaffiliate.com/api/v1/events \
  -H "Authorization: Bearer $SPROUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "booked_call", "ref": "maya", "externalId": "calendly-8812", "note": "Intro call"}'

Response, 201 Created

{
  "ok": true,
  "data": {
    "event": {
      "externalId": "calendly-8812",
      "entryId": "event:3f9c0a1b2d4e5f6a7b8c9d0e",
      "type": "booked_call",
      "name": "Booked call",
      "ref": "maya",
      "amount": 25,
      "occurredAt": "2026-10-06T14:30:00.000Z",
      "recordedAt": "2026-10-06T14:30:04.112Z",
      "note": "Intro call"
    },
    "currency": "USD"
  }
}

The amount and name are locked when the event is recorded. From there the event is an earning like any other: it waits on the Payouts page or approves automatically as your approval settings say (the waiting period before automatic approval counts from when you reported the event, not from occurredAt), you can approve or reject it there, and it is paid, undone, stated, and reported on the 1099-NEC with the affiliate's commission. It is not a referral sale, so it carries no maintenance fee and counts toward no commission tier. entryId is the id it has on the Payouts page and in the affiliate's ledger.

GET /api/v1/deductions read

Unpaid deductions, oldest first: amounts you took off an affiliate's next payout that no payout has taken off yet. Amounts are positive, the amount that comes off. Once a payout takes one off it leaves this list and turns up in that affiliate's ledger as a negative line named Deduction.

{
  "ok": true,
  "data": {
    "deductions": [
      { "id": "cm1x...", "ref": "maya", "name": "Maya Chen", "amount": 25, "note": "Order #1042 was returned after it was paid out" }
    ],
    "count": 1,
    "matched": 1,
    "total": 25,
    "currency": "USD"
  }
}

POST /api/v1/deductions write

curl -s -X POST https://app.sproutaffiliate.com/api/v1/deductions \
  -H "Authorization: Bearer sk_sprout_..." \
  -H "Content-Type: application/json" \
  -d '{"ref":"maya","amount":25,"note":"Order #1042 was returned after it was paid out"}'

Returns 201 with the deduction as stored, its amount positive. There is no idempotency key, so a retried POST takes a second deduction: check GET /api/v1/deductions before retrying one that timed out.

GET /api/v1/payouts read

The payout batches this store has paid, newest first, each with the affiliates in it and what each one was paid.

A batch here is money that left your account through Sprout Affiliate. History imported from a previous affiliate app is left out, exactly as it is on the Payouts page: including it would manufacture batches that never happened.

Request

curl -s "https://app.sproutaffiliate.com/api/v1/payouts?limit=1" \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "batches": [
      {
        "id": "cm4qc9w1x0003l908r2mp7d4s",
        "paidAt": "2026-08-19T18:00:04.512Z",
        "date": "2026-08-19",
        "currency": "USD",
        "via": "paypal",
        "method": "PayPal",
        "total": 486.2,
        "gross": 486.2,
        "taxTotal": 0,
        "taxType": "none",
        "orderCount": 31,
        "affiliateCount": 4,
        "affiliates": [
          {
            "ref": "k7m2p9xd",
            "name": "Sarah Chen",
            "method": "paypal",
            "destination": "sarah@example.com",
            "amount": 212.4,
            "gross": null,
            "tax": null,
            "orderCount": 14
          }
        ]
      }
    ],
    "count": 1,
    "currency": "USD"
  }
}

GET /api/v1/payouts/preview read

Who a payout run would pay right now, and how much, without paying anybody. paypalPayable and paypalTotal are what a "paypal" run would send; holds says why anyone owed is held back. Optional ref previews paying one affiliate.

curl -s https://app.sproutaffiliate.com/api/v1/payouts/preview \
  -H "Authorization: Bearer $SPROUT_KEY"

/api/v1/payouts/schedule read write

GET reads the automatic PayPal payout schedule. PATCH changes it with any of cadence ("off", "weekly", "monthly"), weekday (0 Sunday to 6), monthday (1 to 31), hour (0 to 23), and minute, in the store's timezone. A field left out keeps its value. Turning it on is the Growth plan or above, and never pays for a time already past today.

curl -s -X PATCH https://app.sproutaffiliate.com/api/v1/payouts/schedule \
  -H "Authorization: Bearer $SPROUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cadence": "weekly", "weekday": 5, "hour": 9}'

POST /api/v1/payouts write

"paypal" needs PayPal connected for the store and the Growth plan or above. Who is held back, and why, is decided by the same rules as every other payout run: the minimum payout, missing payout details, a missing tax form, an affiliate who is not active. Those rules are described in Payouts, and this endpoint does not change any of them.

Request

curl -s -X POST https://app.sproutaffiliate.com/api/v1/payouts \
  -H "Authorization: Bearer $SPROUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "manual"}'

Response

{
  "ok": true,
  "data": {
    "mode": "manual",
    "ref": null,
    "ran": true,
    "batchId": "manual-1755624004512",
    "undoable": true,
    "summary": "Recorded 486.20 to 4 affiliates across 31 orders.",
    "details": "Sarah Chen  $212.40 (14 orders)\nNicklaus Reed  $150.20 (9 orders)\n..."
  }
}

GET /api/v1/analytics read

The same four figures the Analytics page shows for the same window, the same chart series behind them, and the same Top affiliates, By program and Products sold tables. products is null rather than empty when the live orders could not be read, and carries showing, total, ordersCounted (how many of the window's referred orders still had line items, which is fewer than the referred-order total once orders are paid) and rows. Nothing is recomputed here: the rows come from the one definition of "a referred order" that the admin page and the Programs table both use, and the window and buckets from the code every chart in the product goes through. Your total and the merchant's total cannot drift apart.

Request

curl -s "https://app.sproutaffiliate.com/api/v1/analytics?range=7&limit=2" \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "range": {
      "from": "2026-08-18",
      "to": "2026-08-24",
      "days": 7,
      "preset": "7",
      "label": "Aug 18 - Aug 24"
    },
    "previousRange": {
      "from": "2026-08-11",
      "to": "2026-08-17",
      "label": "Aug 11 - Aug 17"
    },
    "timezone": "America/New_York",
    "currency": "USD",
    "filters": { "affiliate": "all", "program": "all" },
    "totals": {
      "referredOrders": 41,
      "referredSales": 6218.4,
      "commission": 683.02,
      "affiliatesWithSales": 9
    },
    "granularity": "day",
    "partialLast": true,
    "series": [
      { "key": "2026-08-18", "label": "Aug 18", "referredSales": 812.5, "commission": 89.38, "referredOrders": 6 },
      { "key": "2026-08-19", "label": "Aug 19", "referredSales": 1104, "commission": 121.44, "referredOrders": 8 }
    ],
    "topAffiliates": [
      { "ref": "k7m2p9xd", "name": "Sarah Chen", "referredOrders": 14, "referredSales": 2410.8, "commission": 289.3 },
      { "ref": "nicklaus", "name": "Nicklaus Reed", "referredOrders": 9, "referredSales": 1502, "commission": 150.2 }
    ],
    "byProgram": [
      { "program": "creators", "name": "Creators", "referredOrders": 34, "referredSales": 5488.4, "commission": 604.12 }
    ],
    "liveOrdersUnavailable": false
  }
}

A single day is bucketed by hour and cut at the current hour on your shop's clock, so you never get hours that have not happened yet drawn as zeros.

Webhooks

The API is how you ask Sprout Affiliate something. A webhook is how it tells you, without being asked. Add an endpoint and Sprout Affiliate posts to it when something happens on your store.

1. Open Sprout Affiliate in your Shopify admin, then Settings in the left menu.
2. Click the Developer tab along the top of the page.
3. In the Webhooks card, paste your https:// URL, tick the events you want, and click Add endpoint. To add one from code instead, use POST /api/v1/hooks.
4. Copy the signing secret. It is shown once and never again, the same as an API key.

Ten endpoints per store, counting the ones added from code. Plain http:// is refused, and so are addresses on your own network, because a signed request is worth something and it should only ever leave for a host you control.

Webhooks are on the Professional plan, the same as the API, because they are the same integration seen from the other side. Below it no endpoint can be added, and nothing is delivered to the endpoints already on the store: no request goes out, and no delivery is recorded to replay later. The endpoints themselves are kept, not deleted, and delivery starts again on the upgrade. As with the API, a subscription we cannot read at that moment keeps delivering.

The events

Each payload carries the same shape the API returns for that object, so an integrator reading this page and an integrator handling a webhook are looking at one vocabulary. No API key, no PayPal credential, no password, and no tax identification number is ever sent, whatever the event.

referral.approved and referral.rejected are sent the moment you decide, before the order is priced, so their sale and commission are null. referral.created carries the sale, and the commission wherever the program's rules settle it as the order arrives; it is null where something on the order could still change it, such as a tier, a coupon rate, a product rate, or a rule by customer. GET /api/v1/orders has both for every order. orderId is the form POST /api/v1/orders/:id/approve takes.

On a program that splits commission by clicks, nobody's part is known when the order arrives, so referral.created waits, as the affiliate's "You earned a commission" email does. It is sent once the split is decided: a few minutes after the Web Pixel reports the links the customer clicked, or when the 15-minute wait for that report is over. Its affiliateRef is the affiliate the order counts for, and its commission is that affiliate's own part, the figure on the order's own row in GET /api/v1/orders. Each other affiliate's part is a row of its own there, with part share, and is not in the event.

What arrives

POST https://your-endpoint.example.com/sprout
Content-Type: application/json; charset=utf-8
Sprout-Affiliate-Event: referral.approved
Sprout-Affiliate-Delivery: 7f1c0f2a-...
Sprout-Affiliate-Timestamp: 1787000000
Sprout-Affiliate-Signature: sha256=9c1f...

{
  "id": "7f1c0f2a-...",
  "event": "referral.approved",
  "shop": "your-store.myshopify.com",
  "createdAt": "2026-08-27T19:20:00.000Z",
  "data": { }
}

Verifying it is really us

The signature is an HMAC-SHA256 of the exact bytes of the request body, keyed with that endpoint's signing secret, hex encoded, prefixed with sha256=.

Verify it against the raw body before you parse. Parsing and re-serializing changes the bytes, and the signature will not match a body your framework has rebuilt.

const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  // Constant time, so a wrong signature cannot be found one character at a time.
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Two more things travel with it. Sprout-Affiliate-Timestamp is the same instant as createdAt inside the signed body, so you can cheaply reject anything older than a few minutes and then confirm the header against the signed copy. Sprout-Affiliate-Delivery does not change when we retry, so the same id arriving twice is the same event and the second one should be ignored.

Retries, and what failure looks like

We wait 8 seconds for an answer, and try three times in all, 1 second and then 4 seconds apart. A 2xx is a success and anything else is not.

We retry a timeout, a 408, a 429, and any 5xx. We do not retry other 4xx responses: those are your endpoint saying the request itself is wrong, and sending identical bytes again cannot fix that.

After that the delivery stays failed, with the status code and the error, and it is listed under the endpoint in the Developer tab with a Replay button. A replay sends the stored bytes exactly, same id and same signature, so it is safe to press twice.

Nothing in Sprout Affiliate waits on your endpoint. An affiliate is approved and a payout is recorded in exactly the same way whether you answer in 50 milliseconds, time out, or are down for a day. A slow endpoint costs you a retry, never a merchant a broken page.

Return quickly, then do the work. Acknowledge with a 200 as soon as you have the body, and process it afterwards. An endpoint that finishes its own job before answering is the one that hits the 8 second timeout and gets sent the same event twice.

GET /api/v1/hooks read

Your webhook endpoints, newest first, whether they were added in Settings, by a Zap, or from code. Never a signing secret. No parameters.

Request

curl -s https://app.sproutaffiliate.com/api/v1/hooks \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{
  "ok": true,
  "data": {
    "hooks": [
      {
        "id": "cm9h2k4xq0003l7083w1bq9zd",
        "url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/",
        "events": ["referral.created"],
        "allEvents": false,
        "source": "zapier",
        "active": true,
        "createdAt": "2026-10-03"
      }
    ],
    "count": 1
  }
}

POST /api/v1/hooks write

Add an endpoint from code: subscribe a URL to the events you name, and get its signing secret back once. This is a REST hook, the way an integration asks to be told rather than polling: subscribe when your integration switches on, and delete when it switches off.

The endpoint is the same one Settings adds, under the same rules: https:// only, no address on your own network, no address twice, and ten per store. Deliveries are signed, retried, and listed in Settings > Developer, with Replay, exactly as above. Revoking the key that added an endpoint deletes the endpoint.

Request

curl -s -X POST https://app.sproutaffiliate.com/api/v1/hooks \
  -H "Authorization: Bearer $SPROUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/sprout", "event": "referral.created"}'

Response

{
  "ok": true,
  "data": {
    "hook": {
      "id": "cm9h2k4xq0004l708dk2c8s1a",
      "url": "https://example.com/sprout",
      "events": ["referral.created"],
      "allEvents": false,
      "source": "api",
      "active": true,
      "createdAt": "2026-10-03"
    },
    "secret": "whsec_sprout_6mQ1..."
  }
}

The answer is 201. secret is the key to verify signatures with, and this is the only time it is returned. An address already on the list, an eleventh endpoint, a plain http:// address, or an event Sprout Affiliate does not send is a 400 with the reason in error.

/api/v1/hooks/:id read write

GET returns one endpoint, in the shape GET /api/v1/hooks lists it. DELETE needs a write key and removes the endpoint and its delivery history, wherever it was added.

Request

curl -s -X DELETE https://app.sproutaffiliate.com/api/v1/hooks/cm9h2k4xq0004l708dk2c8s1a \
  -H "Authorization: Bearer $SPROUT_KEY"

Response

{ "ok": true, "data": { "id": "cm9h2k4xq0004l708dk2c8s1a", "deleted": true } }

An id that is not one of your store's endpoints is a 404, including one already deleted. Treat that as done.

What v1 promises

The version is in the path for one reason: so that something you build today keeps working tomorrow, without you watching a changelog.

Inside /api/v1/:

• A field that exists will not be removed, and will not change type. If commission is a number today it is a number forever. If code can be null today, it will not start being "" instead.
• A field's meaning will not change under you. rate will not quietly become a fraction. paid will not quietly start excluding imported history.
• New fields may be added to any response, at any time. Parse what you need and ignore what you do not; a strict parser that rejects unknown keys will break, and that is the one thing you have to build for.
• New endpoints and new optional parameters may be added. Defaults never change, so a call that omits a parameter today gets the same answer tomorrow.
• Enumerated values may gain members. A new payout method or a new order status can appear. Handle an unrecognised value rather than assuming the list on this page is closed forever.

Anything that would break one of those goes in /api/v2/, on its own path, while v1 keeps answering. Your integration does not move until you move it.

Rate limits and refusal wording are the exception to all of the above. Both may be tuned, so read ok and the HTTP status rather than matching on the text of error.