Promotions - Usage Examples

Last Updated: 2026-07-08

All endpoints below are root-level, no /promotions/ or /api/ prefix. See Views for the URL grounding.

Authentication

# Step 1: Obtain token
curl -s -X POST https://api.djanity.com/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "..."}'
# Returns: {"access": "<jwt>", "refresh": "<jwt>"}

# Step 2: All subsequent requests use:
# -H "Authorization: Bearer <token>"

Promotional Campaigns

List all campaigns

curl -s https://api.djanity.com/campaigns/ \
  -H "Authorization: Bearer <token>"

Response:

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "sanity_id": "campaign-summer-2026",
    "campaign_name": "Summer Sale 2026",
    "campaign_type": "seasonal_sale",
    "date_range": {
      "startDate": "2026-06-01T00:00:00Z",
      "endDate": "2026-08-31T23:59:59Z"
    },
    "is_active": true,
    "performance_metrics": {
      "totalRevenue": 0,
      "totalOrders": 0,
      "averageOrderValue": 0
    },
    "created_at": "2026-07-08T10:00:00Z",
    "updated_at": "2026-07-08T10:00:00Z"
  }
]

Create a campaign

curl -s -X POST https://api.djanity.com/campaigns/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "Flash Sale, Bank Holiday",
    "campaign_type": "flash_sale",
    "date_range": {
      "startDate": "2026-05-04T00:00:00Z",
      "endDate": "2026-05-04T23:59:59Z"
    },
    "markdown_schedule": [
      {"effectiveDate": "2026-05-04T00:00:00Z", "discountPercentage": 30}
    ],
    "is_active": true
  }'

Response (201 Created):

{
  "id": "223e4567-e89b-12d3-a456-426614174001",
  "sanity_id": null,
  "campaign_name": "Flash Sale, Bank Holiday",
  "campaign_type": "flash_sale",
  "is_active": true,
  "created_at": "2026-07-08T10:05:00Z"
}

Promo Codes

List all promo codes

curl -s https://api.djanity.com/promo-codes/ \
  -H "Authorization: Bearer <token>"

Response:

[
  {
    "id": "323e4567-e89b-12d3-a456-426614174002",
    "sanity_id": "promo-summer20",
    "name": "Summer 20% Off",
    "code": "SUMMER20",
    "discount_effect": {"type": "percentage", "value": 20},
    "allow_combination": false,
    "date_range": {
      "startDate": "2026-06-01T00:00:00Z",
      "endDate": "2026-08-31T23:59:59Z"
    },
    "current_usage_count": 0,
    "is_active": true
  }
]

Retrieve a promo code by code

curl -s https://api.djanity.com/promo-codes/SUMMER20/ \
  -H "Authorization: Bearer <token>"

Validate a promo code (public, no auth required)

This endpoint is AllowAny, used at checkout to preview discounts without incrementing usage.

curl -s -X POST https://api.djanity.com/promo-codes/validate/ \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER20",
    "subtotal": 100.00,
    "store_id": "store-sanity-id-xyz789"
  }'

Response (valid code):

{
  "valid": true,
  "discount_info": {
    "code": "SUMMER20",
    "name": "Summer 20% Off",
    "discount_type": "percentage",
    "discount_amount": 20.00,
    "message": "Promo code 'SUMMER20' applied! You save $20.00"
  }
}

Response (invalid / expired):

{
  "valid": false,
  "error": "Promo code 'SUMMER20' has expired or reached usage limit",
  "discount_info": null
}

Create a promo code

curl -s -X POST https://api.djanity.com/promo-codes/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Free Shipping October",
    "code": "FREESHIP",
    "discount_effect": {"type": "freeShipping"},
    "allow_combination": true,
    "applies_to": {"scope": "shipping"},
    "date_range": {
      "startDate": "2026-10-01T00:00:00Z",
      "endDate": "2026-10-31T23:59:59Z"
    },
    "usage_restrictions": {"maxUses": 2000},
    "is_active": true
  }'

Auto-Apply Promotions

List active promotions for a store (POS / storefront, public)

curl -s "https://api.djanity.com/promotions/active/?store_id=<django-store-uuid>"

Response:

{
  "promotions": [
    {
      "id": "523e4567-e89b-12d3-a456-426614174010",
      "name": "Buy 2 Get 1 Free, Snacks",
      "description": "Buy 2, Get 1 free",
      "discount_effect": {"type": "bogo", "buyQuantity": 2, "getQuantity": 1},
      "image": null,
      "applies_to": {"scope": "collections", "target_collection_refs": ["collection-snacks"]},
      "eligible_skus": [],
      "savings_preview": "0.00",
      "is_applied": false
    }
  ]
}

eligible_skus is empty on this endpoint because the request carries no cart items. The POS client resolves per-item eligibility client-side.

A/B Tests

List A/B tests

curl -s https://api.djanity.com/ab-tests/ \
  -H "Authorization: Bearer <token>"

Response:

[
  {
    "id": "423e4567-e89b-12d3-a456-426614174003",
    "name": "Summer Sale Pricing Test",
    "campaigns": ["123e4567-e89b-12d3-a456-426614174000"],
    "metric_to_track": "conversion_rate",
    "variant_a_impressions": 5000,
    "variant_a_conversions": 750,
    "variant_b_impressions": 5000,
    "variant_b_conversions": 900,
    "is_active": true,
    "test_duration": {
      "startDate": "2026-06-01T00:00:00Z",
      "endDate": "2026-06-30T23:59:59Z"
    }
  }
]

Record an impression or conversion

curl -s -X POST https://api.djanity.com/ab-tests/423e4567-e89b-12d3-a456-426614174003/record-impression/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"variant": "a"}'

Response:

{"status": "ok", "variant": "a"}

Was this page helpful?