Create loyalty promotion

POST

/v2/loyalty/programs/{program_id}/promotions

Creates a loyalty promotion for a loyalty program.

A loyalty promotion enables buyers to earn points in addition to those earned from the base loyalty program.

This endpoint sets the loyalty promotion to the ACTIVE or SCHEDULED status, depending on the available_time setting. A loyalty program can have a maximum of 10 loyalty promotions with an ACTIVE or SCHEDULED status.

Permissions:LOYALTY_WRITE

Guide

Create loyalty promotions

Try in API Explorer

Link to section

Path parameters

Example code

Link to section

program_id

string

Required

The ID of the loyalty program to associate with the promotion. To get the program ID, call RetrieveLoyaltyProgram using the main keyword.

Link to section

Request body

Link to section

loyalty_promotion

Required

The loyalty promotion to create.

Link to section

idempotency_key

string

Required

A unique identifier for this request, which is used to ensure idempotency. For more information, see Idempotency.

Min Length

Max Length

128

Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

loyalty_promotion

The new loyalty promotion.

curl https://connect.squareup.com/v2/loyalty/programs/d619f755-2d17-41f3-990d-c04ecedd64dd/promotions \ -X POST \ -H 'Square-Version: 2025-06-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "idempotency_key": "ec78c477-b1c3-4899-a209-a4e71337c996", "loyalty_promotion": { "name": "Tuesday Happy Hour Promo", "incentive": { "type": "POINTS_MULTIPLIER", "points_multiplier_data": { "multiplier": "3.0" } }, "available_time": { "time_periods": [ "BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;UNTIL=20221001T000000;BYDAY=TU\nEND:VEVENT" ] }, "trigger_limit": { "times": 1, "interval": "DAY" }, "minimum_spend_amount_money": { "currency": "USD", "amount": 2000 } } }'

{ "loyalty_promotion": { "id": "loypromo_f0f9b849-725e-378d-b810-511237e07b67", "name": "Tuesday Happy Hour Promo", "incentive": { "type": "POINTS_MULTIPLIER", "points_multiplier_data": { "multiplier": "3.000", "points_multiplier": 3 } }, "available_time": { "start_date": "2022-08-16", "end_date": "2022-10-01", "time_periods": [ "BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;UNTIL=20221001T000000;BYDAY=TU\nEND:VEVENT" ] }, "trigger_limit": { "times": 1, "interval": "DAY" }, "minimum_spend_amount_money": { "currency": "USD", "amount": 2000 }, "status": "ACTIVE", "created_at": "2022-08-16T08:38:54Z", "updated_at": "2022-08-16T08:38:54Z", "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd" } }