--- updatedAt: 2026-07-03T01:53:36.000Z agentTools: projectIndex: https://x-series-api.lightspeedhq.com/llms.txt --- # Get a promotion by ID This will retrieve a single promotion using the given ID. ๐Ÿ”’ Requires: `promotions:read` scope # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "contact": { "email": "x-series.api@lightspeedhq.com", "name": "Lightspeed Developer Relations", "url": "https://developers.retail.lightspeed.app" }, "description": "Lightspeed Retail (X-Series) API.", "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "termsOfService": "https://developers.lightspeedhq.com/terms", "title": "API 2026-07", "version": "2026-07" }, "servers": [ { "url": "https://{domain_prefix}.retail.lightspeed.app/api/2026-07", "variables": { "domain_prefix": { "default": "example", "description": "Domain prefix of the store to be operated on" } } } ], "security": [ { "bearerAuth": [] } ], "externalDocs": { "description": "List of tz database time zones", "url": "https://en.wikipedia.org/wiki/List_of_tz_database_time_zones" }, "tags": [ { "description": "Promotion operations", "name": "Promotions" } ], "paths": { "/promotions/{promotion_id}": { "get": { "description": "This will retrieve a single promotion using the given ID.\n\n๐Ÿ”’ Requires: `promotions:read` scope", "operationId": "GetPromotionByID", "parameters": [ { "description": "The promotion id", "in": "path", "name": "promotion_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PromotionResponse" } }, "type": "object" } } }, "description": "" } }, "summary": "Get a promotion by ID", "tags": [ "Promotions" ] } } }, "components": { "schemas": { "Action": { "description": "Action triggered by a promotion.", "properties": { "exclude": { "items": { "$ref": "#/components/schemas/Filter" }, "type": "array" }, "include": { "items": { "$ref": "#/components/schemas/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": "#/components/schemas/Filter" }, "type": "array" }, "include": { "items": { "$ref": "#/components/schemas/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": "#/components/schemas/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", "x-examples": { "example-1": { "code": "string", "created_at": "string", "created_user": { "account_type": "cashier", "created_at": "string", "deleted_at": "string", "display_name": "string", "email": "user@example.com", "email_verified_at": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "image_source": "string", "images": { "original": "string", "sl": "string", "sm": "string", "ss": "string", "st": "string", "standard": "string", "thumb": "string" }, "is_primary_user": true, "permissions": [ "string" ], "restricted_outlet_id": "string", "restricted_outlet_ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "seen_at": "string", "target_daily": 0, "target_monthly": 0, "target_weekly": 0, "updated_at": "string", "username": "string", "version": 0 }, "created_user_id": "string", "group_name": "string", "id": "string", "limit": 0, "promotion_id": "string", "redeemed": 0 } } }, "PromotionPromoCodeSummary": { "nullable": true, "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" }, "PromotionResponse": { "description": "A Promotion defines rules and actions for discounting products as part of a sales promotion.", "properties": { "action": { "$ref": "#/components/schemas/Action" }, "add_promo_code": { "description": "A list of promo codes to associate with this promotion.", "items": { "$ref": "#/components/schemas/PromoCode" }, "type": "array" }, "channels": { "description": "A list of channels for the promotion. Can be `Register`, `Ecommerce`.", "items": { "type": "string" }, "type": "array" }, "combinable_with_coupon": { "description": "Whether this promotion can be combined with an online coupon.", "nullable": true, "type": "boolean" }, "condition": { "$ref": "#/components/schemas/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).", "nullable": true, "type": "string" }, "id": { "description": "Auto-generated object ID.", "type": "string" }, "loyalty_multiplier": { "description": "The loyalty multiplier for the promotion.", "format": "double", "nullable": true, "type": "number" }, "name": { "description": "The name of the promotion.", "type": "string" }, "online_channel_ids": { "description": "A list of online channel IDs for the promotion.", "items": { "type": "integer" }, "type": "array" }, "outlet_ids": { "description": "A list of outlet IDs for the promotion.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "promo_code_summary": { "$ref": "#/components/schemas/PromotionPromoCodeSummary" }, "recurring_promotion": { "allOf": [ { "$ref": "#/components/schemas/RecurringPromotion" } ], "nullable": true, "type": "object" }, "show_potential": { "description": "Whether this promotion is shown as part of potential promotions.", "type": "boolean" }, "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" } }, "title": "Promotion response", "type": "object" }, "RecurringPromotion": { "nullable": true, "properties": { "end_time": { "description": "The time the recurring promotion ends.", "type": "string" }, "id": { "description": "Recurring Promotion ID.", "type": "string" }, "occurrence_type": { "description": "The occurrence type of the recurring promotion.", "type": "string" }, "recurring_promotion_occurrences": { "description": "A list of the promotion occurrences.", "items": { "$ref": "#/components/schemas/RecurringPromotionOccurrence" }, "type": "array" }, "start_time": { "description": "The time the recurring promotion begins.", "type": "string" } }, "title": "Recurring Promotion", "type": "object" }, "RecurringPromotionOccurrence": { "properties": { "day_of_week": { "description": "The day of week of the recurring promotion.", "type": "string" }, "id": { "description": "Recurring Promotion occurrence ID.", "type": "string" } }, "title": "Recurring Promotion occurrence", "type": "object" }, "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.", "nullable": true, "type": "string" }, "display_name": { "description": "Full user's name to be used for display in the UI.", "nullable": true, "type": "string" }, "email": { "description": "User's email address.", "format": "email", "nullable": true, "type": "string" }, "email_verified_at": { "description": "The timestamp of users email verification.", "nullable": true, "type": "string" }, "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.", "nullable": true, "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" }, "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": "#/components/schemas/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" }, "nullable": true, "type": "array" }, "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.", "nullable": true, "type": "string" }, "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": "#/components/schemas/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.", "nullable": true, "type": "number" }, "target_monthly": { "description": "Monthly sales target for the user.", "nullable": true, "type": "number" }, "target_weekly": { "description": "Weekly sales target for the user.", "nullable": true, "type": "number" }, "time_until_deletion": { "description": "The time until the user is deleted.", "nullable": true, "type": "string" }, "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.", "nullable": true, "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" } }, "securitySchemes": { "bearerAuth": { "description": "Bearer Token for API authentication.", "scheme": "bearer", "type": "http" } } } } ```