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

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, never Remix's own HTML error page with a stack trace in 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.

Five endpoints need a write key, and every one of them touches money:

• 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 your 2% usage fee on that sale back.
• POST /api/v1/bonuses creates a debt your store owes, which the next payout run sends.
• PATCH /api/v1/affiliates/:ref changes one affiliate's rate, status, note, or payout method. The rate is money: it is what every referral of theirs from that moment on is calculated at.

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

Thirteen calls across ten 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, in the order they joined.

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
  }
}

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"
    },
    "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).

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. The affiliate is still pending or unverified. Applications are approved in the admin, not here.
• 400 A rate has to be between 0 and 100. The rate is a percentage, not a fraction: send 15, not 0.15.
• 409 on a payout method change when the stored account cannot be read back. The change is refused rather than made with an empty account, because writing one would erase the real one. The affiliate can set the method themselves in their portal.

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,
        "isDefault": true,
        "isReferral": false,
        "cookieDays": 30,
        "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%"
        },
        "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
      }
    ],
    "count": 1,
    "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.

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/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"
  }
}

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 and By program tables. 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.
4. Copy the signing secret. It is shown once and never again, the same as an API key.

Ten endpoints per store. 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.

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.

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.

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.