# List of Sales Web Socket events

Source: https://dev.arcxp.com/subscriptions/sales/learn/list-of-sales-events/

> **Note:**
> 
> If you are using [IFX](https://docs.arcxp.com/alc/?sys%5Fkb%5Fid=ed0c901047aa9510d0cba8b5536d4311&id=kb%5Farticle%5Fview), event names must be prefixed with the namespace `commerce:` i.e. `commerce:PRICE_CHANGE`.
> 
> For all these events involving a _nonce_, the _nonce_ will be valid for 24 hours. After this period, the user or CSR will need to submit a new request. Each _nonce_ can only be used once, and if the same request is made multiple times, only the most recent _nonce_ will be valid.

Keeping Arc XP Subscriptions data in sync with your other systems, including your email newsletter system, is vitally important. Arc XP Subscriptions streams all relevant events via WebSocket, allowing for easy integration. Refer to [How-to-listen-to-websocket-events](https://dev.arcxp.com/subscriptions/identity/build/ifx-email-servic-provider-integration-and-websocket-events/)

## Sales: Shopping Cart Events

### Abandoned cart

`ABANDONED_CART` is sent when an authenticated customer has created an order but failed to complete it within two hours.

The event message will include cart and customer information so you can send a nudge, perhaps even including a discounted offer to persuade the customer to complete the checkout process. Note that no events will be broadcast when the customer is anonymous. This event is generated by the system based on the [Checkout Interaction: Add item to cart](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#checkout-interaction)

```
message: {
  clientId: 'client id',
  skuPriceCodes: [
    {
      sku: 'the SKU that was abandoned',
      priceCode: 'the price code of the SKU that was abandoned'
    }
  ]
}
```

## Sales: Transactions

### Order confirmation

`ORDER_CONFIRMATION` is sent when an order is completed and its status is moved to [Paid](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-csr-perspective/#paid).

```
message: {
  orderNumber
}
```

### Renew Subscription

`RENEW_SUBSCRIPTION` is sent when a subscription is renewed through the renewal engine, by Vindicia, an update in the customer service admin or a partial charge when the [price is updated](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-csr-perspective/#change-product-or-price).

```
message:{
  "subscriptionID":"id of the affected subscription"
  "partialPayment":"true/False"
  "initiatedBy":"clientID of user"
}
```

### Refund Subscription Payment

`REFUND_SUBSCRIPTION_PAYMENT` synchronous event sent when a subscription [payment is refunded](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-csr-perspective/#refund), also if the refund is by a Customer Service [product/price change](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-csr-perspective/#change-product-or-price).

```
message:{
  subscriptionID:"id of the affected subscription"
  initiatedBy
  clientID
}
```

### Fail Renew Subscription

`FAIL_RENEW_SUBSCRIPTION` is sent when a renewal payment fails, initial attempt and as part of a Dunning rule.

```
message:{
  subscriptionID: "the id of the new subscription",
  reason: "a reason string returned by the payment gateway",
  numberOfRetryRules: "number of retry rules configured for the payment provider",
  attempt: "attempt that triggered the message on the stream; 0 (zero) is originally scheduled payment, 1-N are retries",
  dueDate: "date+time the subscription was due to renew"
}
```

### Dunning Reminder

`DUNNING_REMINDER` is sent when when Contact Customer has been selected in a Smart Dunning rule or based on the configuration set for communicating with customers for hard declines.

```
message: {
  subscriptionID
  declineType
  numberOfRetryRules
  gracePeriod
  dueDate
}
```

### IP Checkout Block

`IP_CHECKOUT_BLOCK` is sent when Arc detects that an IP address is abusing the checkout APIs, potentially in an attempt to verify the validity of stolen credit cards. As a response, Arc has temporarily blocked the IP address to prevent further abuse.

```
message:{
  ip
  banInMinues
}
```

### Pending Payment

`PENDING_PAYMENT` is sent when a payment is in a pending status.

```
message: {
  orderNumber,
  subscriptionID
}
```

### Pending Payment Approved

`PENDING_PAYMENT_APPROVED` is sent when a pending payment subscription is approved.

```
message: {
    subscriptionID
}
```

### Pending Payment Declined

`PENDING_PAYMENT_DECLINED` is sent when a pending payment is declined.

```
message: {
    subscriptionID
}
```

## Sales: Subscription Events

### Start subscription

`START_SUBSCRIPTION` is sent when a new subscription is started.

```
message:{
  "subscriptionID": "the id of the new subscription"
}
```

### Terminate subscription

`TERMINATE_SUBSCRIPTION` is sent when the subscription is terminated by the system, or a [CSR](https://docs.arcxp.com/en/products/subscriptions/arc-xp-customer-service-admin-portal/managing-subscriptions.html#UUID-b80376b3-1e56-e6e0-0c41-9360d305fbb0%5Fsection-idm234886519559567).

```
message: {
  subscriptionID: 'the id of the subscription'
}
```

### Cancel subscription

`CANCEL_SUBSCRIPTION` is sent when the subscription is cancelled by a [CSR](https://docs.arcxp.com/en/products/subscriptions/arc-xp-customer-service-admin-portal/managing-subscriptions.html#UUID-b80376b3-1e56-e6e0-0c41-9360d305fbb0%5Fsection-idm234780679183293) or an [end-user](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#cancel-subscription).

```
message: {
  subscriptionID: 'the id of the subscription'
}

// APIs dispatching this event
PUT /sales/public/v1/subscription/{id}/cancel
```

### Restore/Rescue subscription

`RESCUE_SUBSCRIPTION` is sent when a Subscription in canceled status (status === 3) is rescued by a [CSR](https://docs.arcxp.com/en/products/subscriptions/arc-xp-customer-service-admin-portal/managing-subscriptions.html#UUID-b80376b3-1e56-e6e0-0c41-9360d305fbb0%5Fsection-idm234886519171664) or an [end-user](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#rescue-subscription).

```
message: {
  subscriptionID: 'the id of the subscription'
}

// APIs dispatching this event
PUT /sales/public/v1/subscription/{id}/rescue
```

### Extend subscription payment

`EXTEND_SUBSCRIPTION` is sent when a [CSR](https://docs.arcxp.com/en/products/subscriptions/arc-xp-customer-service-admin-portal/managing-subscriptions.html#UUID-b80376b3-1e56-e6e0-0c41-9360d305fbb0%5Fsection-idm23488652067857) extended a subscription’s next renewal date via the Admin portal.

```
message: {
  subscriptionID: 'the id of the subscription'
}
```

### Skip subscription payment

`SKIP_SUBSCRIPTION_PAYMENT` is sent when a [CSR](https://docs.arcxp.com/en/products/subscriptions/arc-xp-customer-service-admin-portal/managing-subscriptions.html#UUID-b80376b3-1e56-e6e0-0c41-9360d305fbb0%5Fsection-idm234886519863437) has skipped the next payment on a subscription via admin portal.

```
message: {
  subscriptionID: 'the id of the subscription'
}
```

### Update Subscription Expiration Date

`UPDATE_SUBSCRIPTION_EXPIRATION_DATE` is sent when the expiration date of a Subscription is [updated](https://docs.arcxp.com/en/products/subscriptions/arc-xp-customer-service-admin-portal/managing-subscriptions.html#UUID-b80376b3-1e56-e6e0-0c41-9360d305fbb0%5Fsection-idm234887869269297).

```
message: {
    subscriptionID: 'id of the affected subscription'
}
```

### Update billing address

`UPDATE_BILLING_ADDRESS` is sent when the billing address is updated by [CSR](https://docs.arcxp.com/en/products/subscriptions/arc-xp-customer-service-admin-portal/managing-subscriptions.html#UUID-b80376b3-1e56-e6e0-0c41-9360d305fbb0%5Fsection-idm234887889938733), or an [end-user](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#update-a-billing-address)

```
   message: {
    subscriptionID: "id of the affected subscription"
    email
    firstName
}

// APIs dispatching this event
PUT /sales/public/v1/subscription/address
```

### Update Payment Method

`UPDATE_PAYMENT_METHOD` is sent when a end-user [updates their payment method](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#payment-method-update). There will be one event per affected subscription.

```
message:{
  "subscriptionID":"id of the affected subscription"
}

// APIs dispatching this event
PUT /sales/public/v1/paymentmethod/{id}/provider/{pid}/finalize
```

### Update product and/or price

`UPDATE_SKU_PRICECODE` is sent when SKU or priceCode of a Subscription is updated. This can happen when the developer API makes a batch price change, a price update is initiated by an [end-user](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#change-price-for-subscription) or a [change in the customer service admin](https://docs.arcxp.com/en/products/subscriptions/arc-xp-customer-service-admin-portal/managing-subscriptions.html#UUID-b80376b3-1e56-e6e0-0c41-9360d305fbb0%5Fsection-idm234886683268594).

```
message: {
    parentSubscriptionID: 'the id of the subscription'
    oldSKU
    newSKU
    oldPriceCode
    newPriceCode
    OldCycleIndex
    newCycleIndex
    effectiveDate
    initiatedBy
}

// APIs dispatching this event
PUT /sales/public/v1/subscription/{id}/finalizePriceUpdate/{initialiseId}
```

### Price Change Scheduled

`PRICE_CHANGE_SCHEDULED_EVENT` is sent when a Price Change is scheduled.

```
message:{
  subscriptionID: 'Subscription ID',
  oldSku: 'old SKU',
  newSku: 'new SKU',
  oldPriceCode: 'old PriceCode',
  newPriceCode: 'new PriceCode',
  oldCycleIndex: oldCycleIndex,
  newCycleIndex: newCycleIndex,
  effectiveDateUTC: 'effective Date UTC'
}
```

### Cancel Scheduled Price Change

`CANCEL_SCHEDULED_PRICE_CHANGE_EVENT` is sent when a scheduled price change is canceled.

```
message: {
subscription ID
oldSKU
newSKU
oldPriceCode
newPriceCode
oldCycleIndex
newCycleIndex
effedtiveDateUTC
}
```

### Upcoming Price Change

`UPCOMING_PRICE_CHANGE_EVENT` is sent when a Price Change was scheduled and this Price Change will take effect in 14 days.

```
message: {
    subscriptionID,
    oldSku,
    newSku,
    oldPriceCode,
    newPriceCode,
    oldCycleIndex,
    newCycleIndex,
    nextEventDateUTC
}
```

### A failed refund in a subscription upgrade/downgrade

The Arc XP system sends the `ACTIVE_SBSC_REFUND_FAILURE` WebSocket event when the subscription update results in a **successful charge but a failed refund**. For more details on the flow, see Subscription updates’ [Steps 1 and 2](https://dev.arcxp.com/subscriptions/sales/configure/user-facing-apis-for-subscription-upgrades/#step-1-post-initialize-and-upgradedowngrade).

The following is an example of a failed refund WebSocket message:

```
{
  index: '1742496674934',
  type: 'ACTIVE_SBSC_REFUND_FAILURE',
  message: {
    clientId: '62bc7fb7-4a42-4ed8-a7fa-f83fe2ea8abe',
    subscriptionId: 3800277923347664
  },
  eventTime: 1742496674934
}
```

## Free subscription events

### Grant Free Subscription

`GRANT_FREE_SUBSCRIPTION` is sent when a customer service agent grants a free subscription.

```
message:{
  "subscriptionID":"the id of the new subscription"
}
```

## Share subscription events

### Share subscription

`INVITE_TO_SHARE` is sent when a subscriber invites someone to [share their subscription](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#share-subscription).

```
message:{
  "subscriptionID":"the id of the parent subscription",
  "redeemCode":"redeem code",
  "email":"email address of invitee"
}
```

### Redeem Subscription

`REDEEM_SHARED_SUBSCRIPTION` is sent when a Subscription is redeemed.

```
message: {
    parentAccountID: 'parent Account ID',
    associateAccountID: 'associate Account ID',
    subscriptionID: 'subscription ID'
}
```

## Group subscription packages events

### Create email domain

`CREATE_EMAIL_DOMAIN` is sent when a new email domain whitelist group subscription is added. It can be created via the admin tool >> Retail >> Group packages >> Create Group Package

```
message:{
  ownerClientID: 'the identity uuid for the group subscription package owner account',
  accessCode: 'code that should be provided to potential group members to access the entitlement',
  emailDomain: 'email domain that group members must have to access entitlement'
  email: 'email of the owner'
  firstName: 'The identity first name of the owner'
}
```

### Delete Email Group Sub

`DELETE_EMAIL_GROUP_SUB` is sent when Retail administrator deletes a Group Packages

```
message:{
  name : Name of Group Packages
}
```

## Gift Subscription events

### Gift Subscription Purchase

`GIFT_SUBSCRIPTION_PURCHASE` is sent when a gift subscription checkout has been completed. The Subscription ID can be used to look up all details of the new gift purchase.

```
message:{
    "subscriptionID": "the id of the new subscription"
}

// APIs dispatching this event
PUT /sales/public/v1/checkout/order/{orderNumber}/payment/{mid}
```

### Gift Recipient Set

`GIFT_RECIPIENT_SET` is sent when a [gift purchaser has set the recipient information for the gift](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#gift-subscription). This can be used to contact the recipient with all the information they need to redeem the gift including a link to a redemption page and instructions on creating an account.

```
message:{
  subscriptionID: "the id of the subscription",
  recipientName,
  recipientEmail,
  redeemCode,
  sku,
  priceCode,
  note,
  sendNotificationOn
}

// APIs dispatching this event
PUT /sales/public/v1/subscription/gift/{redeemCode}
```

### Gift Redeemed

`GIFT_REDEEMED` is sent when a recipient has completed the redemption process to [claim their gift subscription](https://dev.arcxp.com/subscriptions/sales/learn/subscription-management-reader-experience/#gift-subscription). The account ID information can be used to look up details of the subscription if you would like to contact the gift purchaser or redeemer.

```
message:{
  gifterAccountID,
  redeemerAccountID,
  gifterSubscriptionID,
  redeemerSubscriptionID
}

// APIs dispatching this event
POST /sales/public/v1/subscription/gift/redeem
```

## Subscription Migration

### Subscription Migration

`SUBSCRIPTION_MIGRATION` is sent when a batch of subscriptions are migrated.

```
message: {
    batchID,
    success: true | false,
    subscriptionID,
    legacyID,
    messages,
}

// APIs dispatching this event
POST /sales/api/v1/migrate
```

### Subscription Payment Migration

`SUBSCRIPTION_PAYMENT_MIGRATION` is sent when a batch of Payment Subscriptions are migrated.

```
message: {
    legacySubscriptionID,
    batchID,
    success,
    messages
}

// APIs dispatching this event
POST /sales/api/v1/migrate
```

## IFX Events

### Cart add

`CART_ADD` is sent before/after an item is added to the cart.

> **Note:**
>
> Note: If you are using IFX, the before/after events are
>
> - commerce:CART\_ADD\_BEFORE
> - commerce:CART\_ADD\_AFTER

### Order Create

`ORDER_CREATE` synchronous event is sent before/after an order is created based on the user’s cart.

> **Note:**
>
> Note: If you are using IFX, the before/after events are
>
> - commerce:ORDER\_CREATE\_BEFORE
> - commerce:ORDER\_CREATE\_AFTER

### Finalize payment

`FINALIZE_PAYMENT` is sent before/after a payment is finalized

> **Note:**
>
> Note: If you are using IFX, the before/after events are
>
> - commerce:FINALIZE\_PAYMENT\_BEFORE
> - commerce:FINALIZE\_PAYMENT\_AFTER

### Capture Failure Notification

`IFX_CAPTURE_FAILURE_NOTIFICATION` sent when capture failed from IFX BYO PG

```
message: {
  orderNumber
  amount
  currency
  paymentId
  subscriptionId
  token
  message
}
```

### Charge Failure Notification

`IFX_CHARGE_FAILURE_NOTIFICATION` is sent when Renewal/Instant Charge (while PriceUpdate by User) failed from IFX BYO PG

```
message: {
  orderNumber
  amount
  currency
  paymentId
  subscriptionId
  token
  message
}
```

### Finalize Payment Failure Notification

`IFX_FINALIZE_PAYMENT_FAILURE_NOTIFICATION` is sent when finalize payment failed from IFX BYO PG while Checkout

```
message: {
  orderNumber
  amount
  currency
  paymentId
  subscriptionId
  token
  message
}
```

### Finalize Payment Update Failure Notification

`IFX_FINALIZE_PAYMENT_UPDATE_FAILURE_NOTIFICATION` is sent when a payment method update failed from IFX BYO PG

```
message: {
  orderNumber
  amount
  currency
  paymentId
  subscriptionId
  token
  message
}
```

### Refund Failure Notification

`IFX_REFUND_FAILURE_NOTIFICATION` is sent when refund failed from IFX BYO PG

```
message: {
  orderNumber
  amount
  currency
  paymentId
  subscriptionId
  token
  message
}
```

### Event Exception

`IFX_EVENT_EXCEPTION` is sent when the Arc XP system is unable to process response IFX BYO PG for any case

```
message: {
  message
}
```