Update User's Save Points for Swag Settings

In Points Convert to Currency or Points Convert to Rewards loyalty programs, loyalty users earn points on every purchase. By default, these points are automatically converted ("banked") into rewards or currency. However, some loyalty users may prefer to accumulate their points and redeem them for swag instead.

This API lets loyalty users manage their "Save Points for Swag" preference from the mobile app. When the "Save Points for Swag" feature is enabled for the brand, loyalty users can opt in or out of the feature and set a points threshold. Points accumulated up to this threshold are reserved for swag redemption, while points earned above the threshold are automatically converted into rewards or currency. This gives loyalty users flexibility in how they use their points. If a loyalty user no longer wants to save points for swag, they can update their preference to opt out.

Prerequisite

Before processing the request, the API verifies that the "Allow members to save points for swag redemption" feature is enabled for the brand on the Punchh platform. If the feature is not enabled, the API returns an appropriate error code and message.

Note: Contact your Punchh representative to update this Punchh platform configuration.

On success, the API responds with a 200 OK status.

See Get User's Save Points for Swag Settings and Balance, Fetch Available User's Swag, Redeem Swag, and Get Swag Shipping Details.

Headers

Authorization
Type: string
required

Used to authorize the request with access_token. It should be supplied as Bearer ACCESS_TOKEN_GOES_HERE.
x-pch-digest
Type: string
required

The signature for the API call
Content-Type
Type: string
required

Set this header to application/json.
Accept
Type: string
required

Advertises which content types the client is able to understand
User-Agent
Type: string
required

Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see User Agent.
punchh-app-device-id
Type: string
required

The app device ID helps Punchh identify each device so that certain rewards can be awarded individually to each device instead of per user. For example, the sign-up reward is given to each device ID to prevent fraudulent sign-ups so that a user cannot do repeated sign-ups from a single device to get rewards. It should not change even if the user resets a device. See the sample code to generate the punchh-app-device-id header.

Body

application/json

client
Type: string
required

OAuth client ID provided by the business
save_points_for_swag_enabled
Type: boolean

Enables (true) or disables (false) the "Save Points for Swag" preference. The "Save Points for Swag" feature must be enabled for the brand.

When enabled, the user's points are accumulated and saved for swag redemption up to the saved_swag_points_threshold.

When disabled, no points are saved for swag, and all points are automatically converted into rewards/currency per the program rules. A null value (or omitting the parameter) is treated as 'false', which disables saving mode and resets saved_swag_points_threshold to 0.

Note: Both save_points_for_swag_enabled and saved_swag_points_threshold parameters can be provided together or independently in a single request. At least one parameter must be provided; omitting both returns a 400 Bad Request error.
saved_swag_points_threshold
Type: integer
min:
0
max:
999999

The member-defined points threshold. Points accumulated up to this limit are reserved for swag and excluded from automated banking conversion. Points above this threshold are automatically converted into rewards or currency.

Must be a non-negative integer. Invalid values (for example, "abc") return a 422 Unprocessable Entity error. The maximum allowed value is 999999; values exceeding this limit also return a 422 Unprocessable Entity error.

If save_points_for_swag_enabled is 'false' or null, this threshold is ignored and treated as 0. If save_points_for_swag_enabled is 'true' and this parameter is omitted, it defaults to 0, meaning no points are reserved for swag, and all points are eligible for automated banking conversion.

Note: Both save_points_for_swag_enabled and saved_swag_points_threshold parameters can be provided together or independently in a single request. At least one parameter must be provided; omitting both returns a 400 Bad Request error.

Responses

application/json
400
Bad Request
- Missing required parameters — "Provide at least one of save_points_for_swag_enabled or saved_swag_points_threshold."
401
Unauthorized
- Missing or invalid access token — "An active access token must be used to query information about the current user."
422
Unprocessable Entity
- Save Points for Swag feature disabled — "Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue."
- Threshold not a number — "Saved swag points threshold is not a number"
- Threshold exceeds maximum — "Saved swag points threshold must be less than or equal to 999999"

put/api2/mobile/user_banking_preferences

curl https://SERVER_NAME_GOES_HERE.punchh.com/api2/mobile/user_banking_preferences \
  --request PUT \
  --header 'Authorization: Bearer ACCESS_TOKEN_GOES_HERE' \
  --header 'x-pch-digest: {{$$.env.signature}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)' \
  --header 'punchh-app-device-id: APP_DEVICE_ID_GOES_HERE' \
  --data '{
  "client": "CLIENT_KEY_GOES_HERE",
  "save_points_for_swag_enabled": true,
  "saved_swag_points_threshold": 500
}'

Show Schema

{
  "save_points_for_swag_enabled": false,
  "saved_swag_points_threshold": 0,
  "swag_balance": 0
}

200 OK — Successful Update