Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Loyalty

  • Create loyalty account

  • Search loyalty accounts

  • Retrieve loyalty account

  • Accumulate loyalty points

  • Adjust loyalty points

  • Search loyalty events

  • Retrieve loyalty program

  • Calculate loyalty points

  • List loyalty promotions

  • Create loyalty promotion

  • Retrieve loyalty promotion

  • Cancel loyalty promotion

  • Create loyalty reward

  • Search loyalty rewards

  • Delete loyalty reward

  • Retrieve loyalty reward

  • Redeem loyalty reward

  • Webhooks

  • loyalty.account.created

  • loyalty.account.deleted

  • loyalty.account.updated

  • loyalty.event.created

  • loyalty.program.created

  • loyalty.program.updated

  • loyalty.promotion.created

  • loyalty.promotion.updated

<- Loyalty API

Loyalty API

All versions ->

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
1
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.

Link to section

Examples

All versions ->

POST /v2/loyalty/programs/{program_id}/promotions
curl https://connect.squareup.com/v2/loyalty/programs/d619f755-2d17-41f3-990d-c04ecedd64dd/promotions \ -X POST \ -H 'Square-Version: 2026-11-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 } } }'

Response JSON

{ "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" } }