You are viewing an old version of the 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

Path Parameters

Example code

Name	Description
`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.

Request Body

Name	Description
`loyalty_promotion LoyaltyPromotion` Required	The loyalty promotion to create.
`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

Response Fields

Name	Description
`errors Error [ ]`	Any errors that occurred during the request.
`loyalty_promotion LoyaltyPromotion`	The new loyalty promotion.

Examples

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: 2023-01-19' \
  -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": {
          "points_multiplier": 3
        }
      },
      "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": {
        "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"
  }
}