API Reference
Promotions API
Developer-authenticated promotion, promo-code, scheduled-deal, and bundle-offer API reference.
SoundSync
Verified endpoints
These endpoints are route-backed in the current platform.
GET
/api/developer/promotions
List promotion overview: promo codes, scheduled deals, offers, and stats.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- filter query
- Returns
- promoCodes[], deals[], offers[], stats.
- Side effects
- None for read endpoints unless noted.
POST
/api/developer/promotions
Create a promo code, scheduled deal, or promotion offer based on type/offerType.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- type or offerType
- productIds/subscriptionProductIds
- discountType percent|amount
- discountValue
- code optional
- startsAt/endsAt optional
- Returns
- 201 created promo code, deal, or offer.
- Side effects
- Writes promo_codes, product_scheduled_deals, or developer_promotion_offers depending on input.
GET
/api/developer/promotions/promo-codes
List promo codes with stats.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- Returns
- promoCodes[], stats.
- Side effects
- None for read endpoints unless noted.
POST
/api/developer/promotions/promo-codes
Create product-scoped or storewide promo code.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- productId optional for storewide fallback
- code
- discountType
- discountValue
- maxRedemptions optional
- expiresAt optional
- Returns
- 201 promoCode.
- Side effects
- Creates promo code and may use first developer product for storewide backing.
PATCH
/api/developer/promotions/promo-codes/:promoCodeId
Update a developer-owned promo code.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- promoCodeId
- active/discount/expiry fields
- Returns
- Updated promoCode.
- Side effects
- Updates promo code through product promo-code service.
GET
/api/developer/promotions/scheduled-deals
List scheduled product deals.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- Returns
- deals[], stats.
- Side effects
- None for read endpoints unless noted.
POST
/api/developer/promotions/scheduled-deals
Create scheduled product deal.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- productId
- salePrice/discount fields
- startsAt
- endsAt
- Returns
- 201 deal.
- Side effects
- Writes product_scheduled_deals.
POST
/api/developer/promotions/deals/:dealId/cancel
Cancel a scheduled deal.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- dealId
- Returns
- Canceled deal.
- Side effects
- Cancels product scheduled deal.
POST
/api/developer/promotions/offers
Create multi-product, product-bundle, subscription-bundle, build-your-own-bundle, bogo, or group-buy offer.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- offerType
- productIds/subscriptionProductIds
- requiredQuantity optional
- rewardQuantity optional
- groupTarget optional
- Returns
- 201 offer; checkout-backed offers may create backing promo code.
- Side effects
- Writes developer_promotion_offers and maybe promo_codes.
GET
/api/developer/promotions/bundles
List bundle-like promotion offers.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- Returns
- offers[] filtered to bundle offer types.
- Side effects
- None for read endpoints unless noted.
POST
/api/developer/promotions/bundles
Create bundle-like promotion offer.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- offerType
- productIds/subscriptionProductIds
- Returns
- 201 offer.
- Side effects
- None for read endpoints unless noted.