API
GuidesWhat’s newGet API token
Core Resources

Customer notification preferencesNew

Notification preferences record whether a Customer has opted in or out of transactional, promotional and replenishment communication over email and SMS, and when and where each choice was last made.

This resource is new in the V2 reference. It also works when you send X-Recharge-Version: 2021-11.

Endpoints

#The notification preferences object

Attributes

  • emailobject
    Details of the customer's notification preferences for email.
    Show child attributesHide child attributes3
    • transactionalobject
      Details of the customer's notification preferences for transactional communication on this channel.
      Show child attributesHide child attributes5
      • statusstring
        Status of the notification preference. unspecified when the customer has never opted in or out.
        Possible values
        accepteddeclinedunspecified
      • last_opt_in_atdatetime · nullable
        The date and time when the customer last opted in.
      • last_opt_in_sourcestring · nullable
        The interface or process through which the customer last opted in.
      • last_opt_out_atdatetime · nullable
        The date and time when the customer last opted out.
      • last_opt_out_sourcestring · nullable
        The interface or process through which the customer last opted out.
    • promotionalobject
      Details of the customer's notification preferences for promotional communication on this channel.
      Show child attributesHide child attributes5
      • statusstring
        Status of the notification preference. unspecified when the customer has never opted in or out.
        Possible values
        accepteddeclinedunspecified
      • last_opt_in_atdatetime · nullable
        The date and time when the customer last opted in.
      • last_opt_in_sourcestring · nullable
        The interface or process through which the customer last opted in.
      • last_opt_out_atdatetime · nullable
        The date and time when the customer last opted out.
      • last_opt_out_sourcestring · nullable
        The interface or process through which the customer last opted out.
    • replenishmentobject
      Details of the customer's notification preferences for replenishment communication on this channel.
      Show child attributesHide child attributes5
      • statusstring
        Status of the notification preference. unspecified when the customer has never opted in or out.
        Possible values
        accepteddeclinedunspecified
      • last_opt_in_atdatetime · nullable
        The date and time when the customer last opted in.
      • last_opt_in_sourcestring · nullable
        The interface or process through which the customer last opted in.
      • last_opt_out_atdatetime · nullable
        The date and time when the customer last opted out.
      • last_opt_out_sourcestring · nullable
        The interface or process through which the customer last opted out.
  • smsobject
    Details of the customer's notification preferences for SMS.
    Show child attributesHide child attributes3
    • transactionalobject
      Details of the customer's notification preferences for transactional communication on this channel.
      Show child attributesHide child attributes5
      • statusstring
        Status of the notification preference. unspecified when the customer has never opted in or out.
        Possible values
        accepteddeclinedunspecified
      • last_opt_in_atdatetime · nullable
        The date and time when the customer last opted in.
      • last_opt_in_sourcestring · nullable
        The interface or process through which the customer last opted in.
      • last_opt_out_atdatetime · nullable
        The date and time when the customer last opted out.
      • last_opt_out_sourcestring · nullable
        The interface or process through which the customer last opted out.
    • promotionalobject
      Details of the customer's notification preferences for promotional communication on this channel.
      Show child attributesHide child attributes5
      • statusstring
        Status of the notification preference. unspecified when the customer has never opted in or out.
        Possible values
        accepteddeclinedunspecified
      • last_opt_in_atdatetime · nullable
        The date and time when the customer last opted in.
      • last_opt_in_sourcestring · nullable
        The interface or process through which the customer last opted in.
      • last_opt_out_atdatetime · nullable
        The date and time when the customer last opted out.
      • last_opt_out_sourcestring · nullable
        The interface or process through which the customer last opted out.
    • replenishmentobject
      Details of the customer's notification preferences for replenishment communication on this channel.
      Show child attributesHide child attributes5
      • statusstring
        Status of the notification preference. unspecified when the customer has never opted in or out.
        Possible values
        accepteddeclinedunspecified
      • last_opt_in_atdatetime · nullable
        The date and time when the customer last opted in.
      • last_opt_in_sourcestring · nullable
        The interface or process through which the customer last opted in.
      • last_opt_out_atdatetime · nullable
        The date and time when the customer last opted out.
      • last_opt_out_sourcestring · nullable
        The interface or process through which the customer last opted out.
The notification preferences object
{
  "notification_preferences": {
    "email": {
      "transactional": {
        "status": "accepted",
        "last_opt_in_at": "2026-08-03T15:22:10+00:00",
        "last_opt_in_source": "api",
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "promotional": {
        "status": "declined",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": "2026-08-20T09:41:55+00:00",
        "last_opt_out_source": "customer_portal"
      },
      "replenishment": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      }
    },
    "sms": {
      "transactional": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "promotional": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "replenishment": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      }
    }
  }
}

#Retrieve a customer's notification preferences

GET/customers/{id}/notification_preferences
Retrieves the notification preferences of a Customer. Preferences that the customer has never set are returned with a status of unspecified.
Scoperead_customers
GET/customers/{id}/notification_preferences
curl 'https://api.rechargeapps.com/customers/129593/notification_preferences' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "notification_preferences": {
    "email": {
      "transactional": {
        "status": "accepted",
        "last_opt_in_at": "2026-08-03T15:22:10+00:00",
        "last_opt_in_source": "api",
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "promotional": {
        "status": "declined",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": "2026-08-20T09:41:55+00:00",
        "last_opt_out_source": "customer_portal"
      },
      "replenishment": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      }
    },
    "sms": {
      "transactional": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "promotional": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "replenishment": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      }
    }
  }
}

#Update a customer's notification preferences

PUT/customers/{id}/notification_preferences
Updates one or more notification preferences of a Customer. Only the preferences passed in the request are changed, and the opt in or opt out time is set to the time of the request. The response contains the preferences changed by the request; preferences that were not changed are returned with their default values.
Scopewrite_customers

Body parameters

  • emailobject
    The email notification preferences to update.
    Show child attributesHide child attributes3
    • transactionalobject
      The preference for transactional communication on this channel. status is required when this object is passed.
      Show child attributesHide child attributes3
      • statusstring
        The new status of the notification preference.
        Possible values
        accepteddeclined
      • last_opt_in_sourcestring
        The interface or process through which the customer opted in. Used when status is accepted.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
      • last_opt_out_sourcestring
        The interface or process through which the customer opted out. Used when status is declined.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    • promotionalobject
      The preference for promotional communication on this channel. status is required when this object is passed.
      Show child attributesHide child attributes3
      • statusstring
        The new status of the notification preference.
        Possible values
        accepteddeclined
      • last_opt_in_sourcestring
        The interface or process through which the customer opted in. Used when status is accepted.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
      • last_opt_out_sourcestring
        The interface or process through which the customer opted out. Used when status is declined.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    • replenishmentobject
      The preference for replenishment communication on this channel. status is required when this object is passed.
      Show child attributesHide child attributes3
      • statusstring
        The new status of the notification preference.
        Possible values
        accepteddeclined
      • last_opt_in_sourcestring
        The interface or process through which the customer opted in. Used when status is accepted.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
      • last_opt_out_sourcestring
        The interface or process through which the customer opted out. Used when status is declined.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
  • smsobject
    The SMS notification preferences to update.
    Show child attributesHide child attributes3
    • transactionalobject
      The preference for transactional communication on this channel. status is required when this object is passed.
      Show child attributesHide child attributes3
      • statusstring
        The new status of the notification preference.
        Possible values
        accepteddeclined
      • last_opt_in_sourcestring
        The interface or process through which the customer opted in. Used when status is accepted.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
      • last_opt_out_sourcestring
        The interface or process through which the customer opted out. Used when status is declined.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    • promotionalobject
      The preference for promotional communication on this channel. status is required when this object is passed.
      Show child attributesHide child attributes3
      • statusstring
        The new status of the notification preference.
        Possible values
        accepteddeclined
      • last_opt_in_sourcestring
        The interface or process through which the customer opted in. Used when status is accepted.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
      • last_opt_out_sourcestring
        The interface or process through which the customer opted out. Used when status is declined.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
    • replenishmentobject
      The preference for replenishment communication on this channel. status is required when this object is passed.
      Show child attributesHide child attributes3
      • statusstring
        The new status of the notification preference.
        Possible values
        accepteddeclined
      • last_opt_in_sourcestring
        The interface or process through which the customer opted in. Used when status is accepted.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
      • last_opt_out_sourcestring
        The interface or process through which the customer opted out. Used when status is declined.
        Possible values
        apibulk_updateconciergecustomer_portalcustomer_smsmerchant_portalrecharge_checkoutrechargesms_appsci_cartscriptshopify_checkoutsms_reminderstore_opt_in_widgetsubscription_checkout_extensionthank_you_page
  • email_addressstring · nullable
    The email address the consent applies to. Recorded with the change when email preferences are updated.
  • phone_numberstring · nullable
    The phone number the consent applies to. Recorded with the change when SMS preferences are updated.
  • source_detailsobject · nullable
    Additional free-form details about where the consent was collected.
  • attestation_providedboolean · nullable
    Whether the customer's consent was attested to when it was collected.
PUT/customers/{id}/notification_preferences
curl -X PUT 'https://api.rechargeapps.com/customers/129593/notification_preferences' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "notification_preferences": {
    "email": {
      "transactional": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "promotional": {
        "status": "accepted",
        "last_opt_in_at": "2026-09-02T11:05:42+00:00",
        "last_opt_in_source": "api",
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "replenishment": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      }
    },
    "sms": {
      "transactional": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "promotional": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      },
      "replenishment": {
        "status": "unspecified",
        "last_opt_in_at": null,
        "last_opt_in_source": null,
        "last_opt_out_at": null,
        "last_opt_out_source": null
      }
    }
  }
}