Discount

Overview

The Discount extension allows businesses to offer promotional codes, automatic cart-based discounts, and loyalty program rewards during checkout.

Discount Types

Apply Promo Code

POST /checkout/sessions/{session_id}/discounts
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "type": "promo_code",
  "code": "SAVE20"
}

Response

{
  "discount": {
    "id": "disc_abc123",
    "type": "promo_code",
    "code": "SAVE20",
    "description": "20% off your order",
    "value": {
      "type": "percentage",
      "amount": 20
    },
    "applied_amount": 29.99
  },
  "cart": {
    "subtotal": 149.99,
    "discount": -29.99,
    "shipping": 5.99,
    "tax": 11.34,
    "total": 137.33
  }
}

Discount Value Types

// Percentage discount
{
  "value": {
    "type": "percentage",
    "amount": 20  // 20% off
  }
}

// Fixed amount discount
{
  "value": {
    "type": "fixed",
    "amount": 25.00,  // $25 off
    "currency": "USD"
  }
}

// Free shipping
{
  "value": {
    "type": "free_shipping"
  }
}

// Buy X Get Y
{
  "value": {
    "type": "bogo",
    "buy_quantity": 2,
    "get_quantity": 1,
    "get_discount": 100  // 100% off the free item
  }
}

Get Available Discounts

GET /checkout/sessions/{session_id}/discounts/available
Authorization: Bearer {access_token}

Response

{
  "available_discounts": [
    {
      "id": "disc_auto_1",
      "type": "automatic",
      "description": "Free shipping on orders over $100",
      "value": {
        "type": "free_shipping"
      },
      "conditions": {
        "min_subtotal": 100.00
      },
      "applicable": true
    },
    {
      "id": "disc_loyalty_1",
      "type": "loyalty",
      "description": "Gold Member: 10% off",
      "value": {
        "type": "percentage",
        "amount": 10
      },
      "applicable": true
    }
  ],
  "applied_discounts": [
    {
      "id": "disc_abc123",
      "type": "promo_code",
      "code": "SAVE20"
    }
  ]
}

Remove Discount

DELETE /checkout/sessions/{session_id}/discounts/{discount_id}
Authorization: Bearer {access_token}

Stacking Rules

Businesses define how discounts can be combined:

• stackable - Can be combined with other discounts
• exclusive - Cannot be combined with other promo codes
• best_deal - System applies the best single discount

{
  "discount": {
    "id": "disc_abc123",
    "stacking": "exclusive",
    "excludes": ["promo_code"]  // Can't combine with other promo codes
  }
}

Error Handling

• INVALID_PROMO_CODE - Code not recognized
• PROMO_CODE_EXPIRED - Code is no longer valid
• PROMO_CODE_LIMIT_REACHED - Maximum uses exceeded
• MIN_PURCHASE_NOT_MET - Cart doesn't meet minimum
• NOT_STACKABLE - Discount can't be combined

Next Steps

• Learn about AP2 Mandates for agent authorization
• See Checkout Capability for the full flow
• Explore AI Agent Integration for autonomous discounts