ASSN v2 notification types, explained

Types that move commission

The six types Attribloom's engine acts on: accrue, claw back, or re-accrue.

• SUBSCRIBED

  Moves moneyINITIAL_BUYRESUBSCRIBE

  The customer subscribed to an auto-renewable subscription. INITIAL_BUY is a first purchase (or first access through Family Sharing). RESUBSCRIBE means the customer came back to the same subscription, or to another one in the same subscription group.

  Commission effect: Accrues the initial commission for the attributed affiliate. A RESUBSCRIBE resumes an existing subscription lineage, so it accrues as a renewal rather than a new initial.

• DID_RENEW

  Moves moneyBILLING_RECOVERY

  The subscription successfully renewed for a new period. BILLING_RECOVERY means a subscription that previously failed to renew has recovered. No subtype means a normal auto-renewal.

  Commission effect: Accrues a renewal commission for the same affiliate who drove the subscription.

• OFFER_REDEEMED

  Moves moneyUPGRADEDOWNGRADE

  A customer with an active subscription redeemed a subscription offer. UPGRADE takes effect immediately; DOWNGRADE takes effect at the next renewal. No subtype means the offer applied to the active subscription. Offer codes for one-time products arrive as ONE_TIME_CHARGE instead.

  Commission effect: Accrues commission: as an initial purchase when Apple sends it with an INITIAL_BUY subtype (offer-code first purchases), otherwise as a renewal.

• REFUND

  Moves money

  The App Store refunded a transaction. Applies to consumables, non-consumables, auto-renewable subscriptions, and non-renewing subscriptions. The transaction payload carries revocationDate and revocationReason.

  Commission effect: Reverses the matching commission with a clawback entry against the affiliate's pending balance. History is never deleted, so the ledger still sums correctly.

• REFUND_REVERSED

  Moves money

  The App Store reversed a previously granted refund because the customer's dispute resolved against them. If your app revoked content over the refund, reinstate it.

  Commission effect: Re-accrues the commission that the original refund clawed back.

• REVOKE

  Moves money

  An In-App Purchase obtained through Family Sharing is no longer available: the purchaser disabled sharing, someone left the family group, or the purchaser received a refund.

  Commission effect: Claws back only when the REVOKE is an actual refund (a revocationReason is present on a purchased copy). Family Sharing removals move no money, so nothing is reversed for them.

Lifecycle and administrative types

Signals worth logging and alerting on, but no money moves when they arrive.

• CONSUMPTION_REQUEST

  The customer initiated a refund request and the App Store is asking you to provide consumption data to inform the refund decision.

  Commission effect: No ledger movement, but it is an early signal that a REFUND notification may follow.

• DID_CHANGE_RENEWAL_PREF

  UPGRADEDOWNGRADE

  The customer changed their subscription plan. UPGRADE applies immediately with a prorated refund of the unused period; DOWNGRADE applies at the next renewal. No subtype means the customer canceled a pending downgrade.

  Commission effect: No commission action. The money moves on the resulting purchase or renewal event.

• DID_CHANGE_RENEWAL_STATUS

  AUTO_RENEW_ENABLEDAUTO_RENEW_DISABLED

  The customer turned subscription auto-renewal on or off. The App Store also turns auto-renew off after the customer requests a refund.

  Commission effect: No commission action. Useful as a churn signal ahead of an EXPIRED.

• DID_FAIL_TO_RENEW

  GRACE_PERIOD

  A renewal failed over a billing issue and the subscription entered the billing retry period. With the GRACE_PERIOD subtype, keep providing service through the grace period. Apple retries billing for up to 60 days.

  Commission effect: No ledger movement. If the retry later succeeds you receive DID_RENEW with BILLING_RECOVERY, and the renewal accrues then.

• EXPIRED

  VOLUNTARYBILLING_RETRYPRICE_INCREASEPRODUCT_NOT_FOR_SALE

  The subscription expired: the customer turned renewal off (VOLUNTARY), billing retry ran out (BILLING_RETRY), the customer declined a price increase that needed consent (PRICE_INCREASE), or the product was not for sale at renewal time (PRODUCT_NOT_FOR_SALE).

  Commission effect: No commission action. Commission already earned on past periods stays earned; nothing new accrues.

• EXTERNAL_PURCHASE_TOKEN

  CREATEDACTIVE_TOKEN_REMINDERUNREPORTED

  Applies only to apps using the External Purchase API for alternative payments. Carries the external purchase token that you must report to Apple.

  Commission effect: No commission action. Attribloom accrues on App Store transactions.

• GRACE_PERIOD_EXPIRED

  The billing grace period ended without a successful renewal, so you can stop providing service. Apple keeps retrying billing for up to 60 days total.

  Commission effect: No ledger movement.

• METADATA_UPDATE

  You changed a subscription's metadata through the Change Subscription Metadata endpoint. Advanced Commerce API apps only.

  Commission effect: No commission action.

• MIGRATION

  You migrated a subscription to the Advanced Commerce API through its migration endpoint. Advanced Commerce API apps only.

  Commission effect: No commission action.

• ONE_TIME_CHARGE

  The customer purchased a consumable, non-consumable, or non-renewing subscription, or received access to a non-consumable through Family Sharing. Check offerType in the transaction payload to see whether an offer was redeemed.

  Commission effect: No commission action today. Attribloom accrues on auto-renewable subscription notifications.

• PRICE_CHANGE

  You called the Change Subscription Price endpoint. Advanced Commerce API apps only.

  Commission effect: No commission action.

• PRICE_INCREASE

  PENDINGACCEPTED

  The system informed the customer of a subscription price increase. PENDING means a consent-requiring increase the customer has not answered; ACCEPTED means the customer consented, or the increase did not require consent.

  Commission effect: No commission action. Future renewals simply accrue on the new price.

• REFUND_DECLINED

  The App Store declined the customer's refund request.

  Commission effect: No ledger movement. The original commission stands.

• RENEWAL_EXTENDED

  The App Store extended a specific subscription's renewal date at your request through the App Store Server API.

  Commission effect: No commission action.

• RENEWAL_EXTENSION

  SUMMARYFAILURE

  Progress of a bulk renewal-date extension you requested for all eligible subscribers. SUMMARY means the extension completed for everyone eligible; FAILURE reports one subscription it did not work for.

  Commission effect: No commission action.

• RESCIND_CONSENT

  A parent or guardian withdrew consent for a child's app usage.

  Commission effect: No commission action.

• TEST

  Sent only when you request it through the Request a Test Notification endpoint, to prove your server receives notifications. It carries no transaction payload.

  Commission effect: No money movement. Useful to prove your endpoint receives and verifies Apple's signed payloads before real traffic arrives.

Questions

Which notification types affect affiliate commission?

Six of the twenty-three. SUBSCRIBED, DID_RENEW, and OFFER_REDEEMED accrue commission; REFUND claws it back; REFUND_REVERSED restores what a refund clawed back; and REVOKE claws back only when it represents an actual refund. Every other type is a lifecycle or administrative signal that moves no money.

What is the difference between REFUND and REVOKE?

REFUND always means money went back to the customer, so the matching commission is reversed. REVOKE means a Family Sharing entitlement went away, which may or may not involve a refund: check revocationReason on the transaction. A REVOKE without a revocation reason moved no money, so reversing commission for it would be wrong.

What does DID_RENEW with the BILLING_RECOVERY subtype mean?

A subscription that had failed to renew over a billing issue recovered during Apple's retry period and billed successfully. Treat it as a normal renewal: the customer paid, and renewal commission accrues.

Do TEST notifications include a transaction?

No. TEST arrives only when you request it and carries no signedTransactionInfo. It is the cheapest way to prove your endpoint receives Apple's notifications and verifies the JWS signature before any real purchase happens.