Promotions

Creates, retrieves, updates, and deletes promotions.

Table Specific Information

Select

The driver uses the BigCommerce API to process WHERE clause conditions built with the following columns and operators:

Id supports the = comparison.
Name supports the = comparison.
RedemptionType supports the = comparison.
Status supports the = comparison.
CurrencyCode supports the = comparison.

The rest of the filter is executed client-side within the driver.

For example, the following queries are processed server-side:

SELECT * FROM Promotions WHERE Id = 10

SELECT * FROM Promotions WHERE Status = 'ENABLED'

Insert

To insert a promotion, specify at least the Name, RedemptionType, StartDate, CurrencyCode, and Rules columns. Rules must be a JSON-formatted array of rule objects.

INSERT INTO Promotions (Name, RedemptionType, StartDate, CurrencyCode, Rules) VALUES ('Free Shipping', 'AUTOMATIC', '2024-01-01T00:00:00Z', '*', '[{"action":{"shipping":{"zone_ids":"*"}}}]')

Update

UPDATE Promotions SET  MaxUses=20,MaxUsesPerCustomer=5,Schedule='{"week_frequency":2,"week_days":["Wednesday"],"daily_start_time":"10:00:00","daily_end_time":"23:00:00"}',
    Notifications='[{"content":"Congratulations! Youʼve received a free %ACTION.FREE_PRODUCT%!","type":"UPSELL", "locations":["HOME_PAGE","CART_PAGE"]}]' WHERE Id = 3

Delete

DELETE FROM Promotions WHERE Id = 10

Columns


Name	Type	ReadOnly	Description
Id [KEY]	Integer	True	The unique identifier of the promotion.
Name	String	False	Internal, merchant-facing name for the promotion.
DisplayName	String	False	Customer-facing name for the promotion.
RedemptionType	String	False	Whether the promotion is redeemed via a coupon code or applied automatically. The allowed values are COUPON, AUTOMATIC.
Status	String	False	The status of the promotion. The allowed values are ENABLED, DISABLED, INVALID.
StartDate	Datetime	False	Date and time the promotion becomes active.
EndDate	Datetime	False	Date and time the promotion expires. Leave empty for a promotion with no end date.
CurrencyCode	String	False	The ISO-4217 currency code this promotion applies to, or * for all currencies.
MaxUses	Integer	False	The maximum number of times the promotion can be used in total.
MaxUsesPerCustomer	Integer	False	The maximum number of times a single customer can use the promotion. Only applies to coupon-type promotions.
CurrentUses	Integer	True	The number of times the promotion has been used.
Stop	Boolean	False	Whether this promotion prevents any further promotions from applying.
CanBeUsedWithOtherPromotions	Boolean	False	Whether this promotion can be combined with other promotions. Defaults to true.
CouponType	String	False	Whether the promotion uses a single shared coupon code or bulk-generated unique codes. Only applies to coupon-type promotions. The allowed values are SINGLE, BULK.
CouponOverridesAutomaticWhenOfferingHigherDiscounts	Boolean	False	Whether this coupon promotion overrides an automatic promotion when it offers a higher discount.
CreatedFrom	String	True	Where the promotion was created from. The allowed values are react_ui, legacy_ui, api.
Rules	String	False	A JSON-formatted array of discount rules and actions for this promotion.
ChannelIds	String	False	A JSON-formatted array of channel Ids this promotion is restricted to. Empty applies to all channels.
Customer	String	False	A JSON-formatted object describing customer eligibility criteria for this promotion.
Notifications	String	False	A JSON-formatted array of notification settings for this promotion.
Schedule	String	False	A JSON-formatted object describing recurring schedule settings for this promotion.
Codes	String	True	A JSON-formatted object with coupon code usage details. Only present for coupon-type promotions.
ShippingAddress	String	False	A JSON-formatted object that specifies which addresses to consider.