Promotion

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/lightspeed/main/json-schema/lightspeed-promotion-schema.json",
  "title": "Promotion",
  "description": "A Promotion defines rules and actions for discounting products as part of a sales promotion.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lightspeed-promotions-api-openapi.yml#/components/schemas/Promotion",
  "properties": {
    "action": {
      "$ref": "#/$defs/Action"
    },
    "add_promo_code": {
      "description": "A list of promo codes to associate with this promotion.",
      "items": {
        "$ref": "#/$defs/PromoCode"
      },
      "type": "array"
    },
    "channels": {
      "description": "A list of channels for the promotion. Can be `Register`, `Ecommerce`.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "condition": {
      "$ref": "#/$defs/Condition"
    },
    "customer_group_ids": {
      "description": "A list of customer group IDs for the promotion.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "description": {
      "description": "A short description for the promotion.",
      "type": "string"
    },
    "end_time": {
      "description": "The time the promotion ends, in UTC, e.g. `2006-01-02T15:04:05` (no timezone suffix).",
      "type": [
        "string",
        "null"
      ]
    },
    "id": {
      "description": "Auto-generated object ID.",
      "type": "string"
    },
    "loyalty_multiplier": {
      "description": "The loyalty multiplier for the promotion.",
      "format": "double",
      "type": "number"
    },
    "name": {
      "description": "The name of the promotion.",
      "type": "string"
    },
    "outlet_ids": {
      "description": "A list of outlet IDs for the promotion.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "promo_code_summary": {
      "$ref": "#/$defs/PromotionPromoCodeSummary"
    },
    "start_time": {
      "description": "The time the promotion begins, in UTC, e.g. `2006-01-02T15:04:05` (no timezone suffix).",
      "type": "string"
    },
    "status": {
      "description": "The status of the promotion.",
      "type": "string"
    },
    "use_promo_code": {
      "description": "Whether or not this promotion uses promo codes.",
      "type": "boolean"
    }
  },
  "required": [
    "action",
    "condition",
    "name",
    "start_time",
    "use_promo_code"
  ],
  "type": "object",
  "$defs": {
    "Action": {
      "description": "Action triggered by a promotion.",
      "properties": {
        "exclude": {
          "items": {
            "$ref": "#/$defs/Filter"
          },
          "type": "array"
        },
        "include": {
          "items": {
            "$ref": "#/$defs/Filter"
          },
          "type": "array"
        },
        "max_quantity": {
          "description": "Maximum quantity, if required by the action type.",
          "type": "integer"
        },
        "min_quantity": {
          "description": "Minimum quantity, if required by the action type.",
          "type": "integer"
        },
        "quantity": {
          "description": "Quantity, if required by the action type.",
          "type": "integer"
        },
        "type": {
          "description": "The type of action.",
          "enum": [
            "basic_percent_discount",
            "basic_fixed_discount",
            "fixed_discount",
            "percent_discount",
            "loyalty",
            "fixed_price_discount",
            "fixed_pool_discount",
            "percent_pool_discount"
          ],
          "type": "string"
        },
        "value": {
          "description": "Value associated with the action.",
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "type",
        "value"
      ],
      "title": "Action",
      "type": "object"
    },
    "Condition": {
      "description": "A condition to determine whether a promotion should apply to a sale.",
      "properties": {
        "exclude": {
          "items": {
            "$ref": "#/$defs/Filter"
          },
          "type": "array"
        },
        "include": {
          "items": {
            "$ref": "#/$defs/Filter"
          },
          "type": "array"
        },
        "max_quantity": {
          "description": "Minimum quantity, if required by the condition type.",
          "type": "integer"
        },
        "min_price": {
          "description": "Minimum price, if required by the condition type.",
          "format": "double",
          "type": "number"
        },
        "min_quantity": {
          "description": "Minimum quantity, if required by the condition type.",
          "type": "integer"
        },
        "quantity": {
          "description": "Quantity, if required by the condition type.",
          "minimum": 1,
          "type": "integer"
        },
        "type": {
          "description": "Condition type.",
          "enum": [
            "product_set",
            "sale_price"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "quantity"
      ],
      "title": "Condition",
      "type": "object"
    },
    "Filter": {
      "properties": {
        "field": {
          "description": "name of the filter field",
          "enum": [
            "brand_id",
            "product_id",
            "supplier_id",
            "tag_id",
            "type_id",
            "variant_parent_id"
          ],
          "type": "string"
        },
        "value": {
          "description": "value of the filter field",
          "type": "string"
        }
      },
      "required": [
        "field",
        "value"
      ],
      "title": "Condition Filter",
      "type": "object"
    },
    "PromoCode": {
      "properties": {
        "code": {
          "description": "Code for use in the promotion.",
          "type": "string"
        },
        "created_at": {
          "description": "Time the code was created.",
          "type": "string"
        },
        "created_user": {
          "$ref": "#/$defs/User"
        },
        "created_user_id": {
          "description": "Created User ID.",
          "type": "string"
        },
        "group_name": {
          "description": "Name of the group.",
          "type": "string"
        },
        "id": {
          "description": "Auto-generated object ID.",
          "type": "string"
        },
        "limit": {
          "description": "Redemption limit for this promotion.",
          "type": "integer"
        },
        "promotion_id": {
          "description": "Promotion ID.",
          "type": "string"
        },
        "redeemed": {
          "description": "Number of times this code has been redeemed.",
          "type": "integer"
        }
      },
      "required": [
        "code"
      ],
      "title": "Promotion Code",
      "type": "object"
    },
    "PromotionPromoCodeSummary": {
      "properties": {
        "redeemed_amount": {
          "description": "The redeemed amount",
          "type": "integer"
        },
        "total_promo_code": {
          "description": "The total for the promo code",
          "type": "integer"
        }
      },
      "title": "Promotion Promo Code Summary",
      "type": [
        "object",
        "null"
      ]
    },
    "Role": {
      "properties": {
        "id": {
          "description": "Auto-generated object ID.",
          "type": "string"
        },
        "name": {
          "description": "The Role name.",
          "type": "string"
        },
        "system_role_id": {
          "description": "A system role id of the Role. Will be either '100', '200', or '300'.",
          "type": "string"
        }
      },
      "title": "Role",
      "type": "object"
    },
    "User": {
      "properties": {
        "account_type": {
          "description": "User's account type.",
          "enum": [
            "cashier",
            "manager",
            "admin"
          ],
          "type": "string"
        },
        "created_at": {
          "description": "Creation timestamp in UTC.",
          "type": "string"
        },
        "deleted_at": {
          "description": "Deletion timestamp in UTC.",
          "type": [
            "string",
            "null"
          ]
        },
        "display_name": {
          "description": "Full user's name to be used for display in the UI.",
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "description": "User's email address.",
          "format": "email",
          "type": [
            "string",
            "null"
          ]
        },
        "email_verified_at": {
          "description": "The timestamp of users email verification.",
          "type": [
            "string",
            "null"
          ]
        },
        "enabled": {
          "description": "Indicates whether the user is enabled.",
          "type": "boolean"
        },
        "enabled_mfa": {
          "description": "The user's enabled MFA factor, or null if MFA is not enabled.",
          "properties": {
            "created_at": {
              "description": "Timestamp when the MFA factor was created.",
              "type": "string"
            },
            "id": {
              "description": "Auto-generated MFA factor ID.",
              "type": "string"
            },
            "type": {
              "description": "The MFA factor type (e.g. \"otp\").",
              "enum": [
                "otp"
              ],
              "type": "string"
            }
          },
          "type": [
            "object",
            "null"
          ]
        },
        "id": {
          "description": "Auto-generated object ID.",
          "format": "uuid",
          "type": "string"
        },
        "image_source": {
          "description": "URL of the default-sized user's avatar.",
          "type": "string"
        },
        "images": {
          "$ref": "#/$defs/UserImages"
        },
        "is_primary_user": {
          "description": "Indicated whether this user is the primary user for the account.",
          "type": "boolean"
        },
        "permissions": {
          "description": "The permissions assigned to the user.",
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "require_password_change": {
          "description": "Indicates whether the user is required to change their password.",
          "type": "boolean"
        },
        "restricted_outlet_id": {
          "deprecated": true,
          "description": "**deprecated** Use the `restricted_outlet_ids` instead.",
          "type": [
            "string",
            "null"
          ]
        },
        "restricted_outlet_ids": {
          "description": "A list of outlet IDs the user is associated with",
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "type": "array"
        },
        "roles": {
          "description": "The roles assigned to the user.",
          "items": {
            "$ref": "#/$defs/Role"
          },
          "type": "array"
        },
        "rules": {
          "description": "The rules assigned to the user.",
          "type": "object"
        },
        "seen_at": {
          "description": "The timestamp of the user's last activity in the system.",
          "type": "string"
        },
        "switch_id": {
          "description": "The switch id for the user.",
          "type": "string"
        },
        "target_daily": {
          "description": "Daily sales target for the user.",
          "type": [
            "number",
            "null"
          ]
        },
        "target_monthly": {
          "description": "Monthly sales target for the user.",
          "type": [
            "number",
            "null"
          ]
        },
        "target_weekly": {
          "description": "Weekly sales target for the user.",
          "type": [
            "number",
            "null"
          ]
        },
        "time_until_deletion": {
          "description": "The time until the user is deleted.",
          "type": [
            "string",
            "null"
          ]
        },
        "updated_at": {
          "description": "Last update timestamp in UTC.",
          "type": "string"
        },
        "username": {
          "description": "User's username used for login.",
          "type": "string"
        },
        "version": {
          "description": "Auto-incrementing object version number.",
          "format": "int64",
          "type": "integer"
        }
      },
      "required": [
        "account_type",
        "created_at",
        "id",
        "is_primary_user",
        "updated_at",
        "username",
        "version"
      ],
      "title": "User",
      "type": "object"
    },
    "UserImages": {
      "description": "On object containing URLs for different sizes of the user’s avatar.",
      "properties": {
        "original": {
          "type": "string"
        },
        "sl": {
          "type": "string"
        },
        "sm": {
          "type": "string"
        },
        "ss": {
          "type": "string"
        },
        "st": {
          "type": "string"
        },
        "standard": {
          "type": "string"
        },
        "thumb": {
          "type": "string"
        }
      },
      "title": "User Image",
      "type": [
        "object",
        "null"
      ]
    }
  }
}