Affiliate REST

PATCH memberships/:id/terms

Save prospective individual terms for a membership. Existing saved referral contracts are not silently rewritten.

Verified 2026-10-07·Read Markdown

On this page

Purpose

Save prospective individual terms for a membership. Existing saved referral contracts are not silently rewritten.

Authentication and scope

Use an app-scoped affiliate API key with terms:write. Record IDs must belong to the credential's app and workspace. A workspace MCP key or install-bridge key is not interchangeable with this key.

Request

PATCH /api/affiliate-platform/v1/memberships/:id/terms

rules: required; object
effectiveAt: optional; value

Use the exact record identifier returned for your own app.

Set the environment credential from your authenticated Developers screen. Replace the fictional record IDs and shop/contact values. This request changes data; review the effect before running it. Use a new idempotency key for a new action, and reuse the same key/body only when retrying the same action.

bash

curl --request PATCH "https://heycrust.com/api/affiliate-platform/v1/memberships/11111111-1111-4111-8111-111111111111/terms" \
  --header "Authorization: Bearer $HEYCRUST_AFFILIATE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: example-patch-memberships-id-terms-001" \
  --data '{"rules":{"basis":"gross","rateBps":2000,"cpi":{"amountMinor":"0","currency":"USD"},"includedSaleKinds":["subscription_sale"],"durationMonths":12,"holdDays":30,"threshold":{"amountMinor":"5000","currency":"USD"},"windowDays":30,"allowExistingShops":false,"allowManualClaims":true}}'

Response and verification

The response is the operation's program, membership, terms, referral, commission or payout-history representation. Verify its app/record identity and state; acceptance of a request is not proof of an external transfer or attributed Shopify install.

Successful responses use Cache-Control: no-store and X-Affiliate-Schema-Version: 1. Money uses currency plus minor-unit integer strings; currencies stay separate.

Errors and recovery

401 means missing/invalid/revoked credentials; 403 means denied app/scope/resource access. Invalid fields produce 400, unsupported operation/path 404, conflict/source/review conditions 409, and the DB-backed credential quota produces 429 with Retry-After. The public affiliate quota is 120 requests per credential per minute. Validate the response body as well as the status. JSON mutation bodies must fit the 65,536-byte request bound.

Read API overview and Developer integration.

Response example

Successful response excerpt exercised through the actual handler with isolated fixtures. Other fields are omitted. IDs, dates and merchant values are fictional; this is an example state, not a universal outcome.

json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "programId": "11111111-1111-4111-8111-111111111111",
  "target": {
    "kind": "membership",
    "id": "11111111-1111-4111-8111-111111111111"
  },
  "rules": {
    "basis": "gross",
    "rateBps": 2000,
    "durationMonths": 12,
    "holdDays": 30
  },
  "effectiveAt": "2026-10-07T10:00:00.000Z"
}

Complete rules and business constraints

Send the full rules object. Schema acceptance is followed by financial business validation; an object with the right JSON types can still be rejected. Percentage units are basis points: 2000 means 20%, while 20 means 0.2%. Review the intended basis, charge kinds, duration and hold before a write.

Field	Required meaning and constraints
`rules.basis`	Required: gross or net. Gross uses the eligible gross collection basis shown by the product; net uses the corresponding net collection. No FX conversion is invented.
`rules.rateBps`	Required integer basis points from 0 to 10000. 2000 = 20%; 3000 = 30%; 20 = 0.2%. A zero rate requires a positive CPI reward.
`rules.cpi`	Required Money object; amountMinor is a nonnegative integer string and currency is a supported uppercase settlement currency. Zero disables the install reward.
`rules.cpi.amountMinor`	Required nonnegative minor-unit integer string, at most 38 digits; no leading zeros except 0 and no negative zero.
`rules.cpi.currency`	Required supported settlement currency such as USD. Its scale determines minor units; the object has no precision field.
`rules.includedSaleKinds`	Required array containing unique subscription_sale, usage_sale and/or one_time_sale values. Must be nonempty when rateBps is positive.
`rules.durationMonths`	Required positive integer 1–1200 or null for unlimited duration. Calendar anniversaries use the original install date; zero does not mean lifetime.
`rules.holdDays`	Required integer 0–3650: collection holding period in days.
`rules.threshold`	Required nonnegative Money object for the primary payout threshold. Uses amountMinor and supported currency.
`rules.threshold.amountMinor`	Required nonnegative canonical minor-unit integer string, at most 38 digits.
`rules.threshold.currency`	Required supported uppercase settlement currency; keep balances separate.
`rules.windowDays`	Required integer 1–365: attribution/referral window in days.
`rules.allowExistingShops`	Required boolean: eligibility policy for existing shops.
`rules.allowManualClaims`	Required boolean: program-level manual client-claim policy; effective group/membership permissions also matter.
`rules.thresholds`	Optional array of at most 30 Money objects. One nonnegative threshold per currency; currencies must be unique and the primary threshold must be included with the exact same amount. Omission derives the primary threshold only.
`rules.thresholds[].amountMinor`	Required for each listed threshold: nonnegative canonical minor-unit integer string.
`rules.thresholds[].currency`	Required for each listed threshold: supported currency; no duplicates in the array.
`effectiveAt`	Optional ISO datetime; omission uses request time. New rules cannot be retroactive. These are prospective versions, not a rewrite of saved referral contracts.

An effective version may change future offers/eligibility; existing referrals retain their contract snapshot unless a separate reviewed future-contract proposal is accepted. The public API does not interpret rateBps as a whole percentage. See Program contracts and Exact money.

Search documentation