--- title: "RedeemLoyaltyReward" method: POST path: "/v2/loyalty/rewards/{reward_id}/redeem" tags: ["Loyalty"] --- # RedeemLoyaltyReward `POST /v2/loyalty/rewards/{reward_id}/redeem` Redeems a loyalty reward. The endpoint sets the reward to the `REDEEMED` terminal state. If you are using your own order processing system (not using the Orders API), you call this endpoint after the buyer paid for the purchase. After the reward reaches the terminal state, it cannot be deleted. In other words, points used for the reward cannot be returned to the account. ## Path parameters - `reward_id` string, required ## Request body - RedeemLoyaltyRewardRequest — A request to redeem a loyalty reward. - `idempotency_key` string, required — A unique string that identifies this `RedeemLoyaltyReward` request. Keys can be any valid string, but must be unique for every request. - `location_id` string, required — The ID of the [location](entity:Location) where the reward is redeemed. ## Response `200` Success - RedeemLoyaltyRewardResponse — A response that includes the `LoyaltyEvent` published for redeeming the reward. - `errors` Error[] — Any errors that occurred during the request. - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API. - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `event` LoyaltyEvent — Provides information about a loyalty event. For more information, see [Search for Balance-Changing Loyalty Events](https://developer.squareup.com/docs/loyalty-api/loyalty-events). - `id` string, required — The Square-assigned ID of the loyalty event. - `type` 'ACCUMULATE_POINTS' | 'CREATE_REWARD' | 'REDEEM_REWARD' | 'DELETE_REWARD' | 'ADJUST_POINTS' | 'EXPIRE_POINTS' | 'OTHER' | 'ACCUMULATE_PROMOTION_POINTS', required — The type of the loyalty event. - `created_at` string, required — The timestamp when the event was created, in RFC 3339 format. - `accumulate_points` LoyaltyEventAccumulatePoints — Provides metadata when the event `type` is `ACCUMULATE_POINTS`. - `loyalty_program_id` string — The ID of the [loyalty program](entity:LoyaltyProgram). - `points` integer, nullable — The number of points accumulated by the event. - `order_id` string, nullable — The ID of the [order](entity:Order) for which the buyer accumulated the points. This field is returned only if the Orders API is used to process orders. - `create_reward` LoyaltyEventCreateReward — Provides metadata when the event `type` is `CREATE_REWARD`. - `loyalty_program_id` string, required — The ID of the [loyalty program](entity:LoyaltyProgram). - `reward_id` string — The Square-assigned ID of the created [loyalty reward](entity:LoyaltyReward). This field is returned only if the event source is `LOYALTY_API`. - `points` integer, required — The loyalty points used to create the reward. - `redeem_reward` LoyaltyEventRedeemReward — Provides metadata when the event `type` is `REDEEM_REWARD`. - `loyalty_program_id` string, required — The ID of the [loyalty program](entity:LoyaltyProgram). - `reward_id` string — The ID of the redeemed [loyalty reward](entity:LoyaltyReward). This field is returned only if the event source is `LOYALTY_API`. - `order_id` string — The ID of the [order](entity:Order) that redeemed the reward. This field is returned only if the Orders API is used to process orders. - `delete_reward` LoyaltyEventDeleteReward — Provides metadata when the event `type` is `DELETE_REWARD`. - `loyalty_program_id` string, required — The ID of the [loyalty program](entity:LoyaltyProgram). - `reward_id` string — The ID of the deleted [loyalty reward](entity:LoyaltyReward). This field is returned only if the event source is `LOYALTY_API`. - `points` integer, required — The number of points returned to the loyalty account. - `adjust_points` LoyaltyEventAdjustPoints — Provides metadata when the event `type` is `ADJUST_POINTS`. - `loyalty_program_id` string — The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram). - `points` integer, required — The number of points added or removed. - `reason` string, nullable — The reason for the adjustment of points. - `loyalty_account_id` string, required — The ID of the [loyalty account](entity:LoyaltyAccount) associated with the event. - `location_id` string — The ID of the [location](entity:Location) where the event occurred. - `source` 'SQUARE' | 'LOYALTY_API', required — Defines whether the event was generated by the Square Point of Sale. - `expire_points` LoyaltyEventExpirePoints — Provides metadata when the event `type` is `EXPIRE_POINTS`. - `loyalty_program_id` string, required — The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram). - `points` integer, required — The number of points expired. - `other_event` LoyaltyEventOther — Provides metadata when the event `type` is `OTHER`. - `loyalty_program_id` string, required — The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram). - `points` integer, required — The number of points added or removed. - `accumulate_promotion_points` LoyaltyEventAccumulatePromotionPoints — Provides metadata when the event `type` is `ACCUMULATE_PROMOTION_POINTS`. - `loyalty_program_id` string — The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram). - `loyalty_promotion_id` string — The Square-assigned ID of the [loyalty promotion](entity:LoyaltyPromotion). - `points` integer, required — The number of points earned by the event. - `order_id` string, required — The ID of the [order](entity:Order) for which the buyer earned the promotion points. Only applications that use the Orders API to process orders can trigger this event. --- [API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/revisions/6a5164284e41/schema)