• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

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

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.

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

Example:
You are viewing an old version of the API
POST /v2/loyalty/programs/{program_id}/promotions
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js
curl https://connect.squareup.com/v2/loyalty/programs/d619f755-2d17-41f3-990d-c04ecedd64dd/promotions \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -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"
      }
    }
  }'
Response JSON
{
  "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"
    },
    "status": "ACTIVE",
    "created_at": "2022-08-16T08:38:54Z",
    "updated_at": "2022-08-16T08:38:54Z",
    "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
  }
}