Promotions Management

ACP supports managing promotion data through the REST API. Promotions can only be submitted via the API; SFTP file upload is not supported.

5.1 Promotion Object

Field	Type	Required	Description
`id`	string	Yes	Unique promotion identifier
`title`	string	Yes	Promotion name
`description`	string	No	Detailed promotion description
`status`	enum	Yes	Promotion status
`active_period`	DateTimeRange	No	Active time range
`benefits`	Benefit[]	Yes	List of discount types
`applies_to`	ProductTarget	No	Applicable product scope
`url`	URI string	No	Promotion details page URL

Promotion Status

Status	Description
`draft`	Draft, not yet active
`scheduled`	Scheduled, awaiting activation
`active`	Currently active
`expired`	Has expired
`disabled`	Manually disabled

Active Time Range

active_period uses the DateTimeRange type, containing start_time and end_time fields:

{
  "active_period": {
    "start_time": "2026-04-01T00:00:00Z",
    "end_time": "2026-04-30T23:59:59Z"
  }
}

Product Targeting

applies_to uses the ProductTarget type to specify which products the promotion applies to:

{
  "applies_to": {
    "product_id": "prod_001",
    "variant_ids": ["var_001_black", "var_001_white"]
  }
}

If variant_ids is not specified, the promotion applies to all variants of that product.

5.2 Three Discount Types

Fixed Amount Discount (AmountOffBenefit)

{
  "type": "amount_off",
  "amount_off": {
    "amount": 1000,
    "currency": "USD"
  }
}

Deducts a fixed amount. The example above represents a $10.00 USD discount (amounts use minor units, i.e., cents).

Percentage Discount (PercentOffBenefit)

{
  "type": "percent_off",
  "percent_off": 20
}

Deducts by percentage. The example above represents a 20% discount.

Free Shipping (FreeShippingBenefit)

{
  "type": "free_shipping"
}

Waives shipping fees. No additional parameters required.

5.3 Complete Promotion Example

{
  "id": "promo_summer_2026",
  "title": "Summer Sale - 25% Off Electronics",
  "description": "All electronics 25% off during summer promotion",
  "status": "scheduled",
  "active_period": {
    "start_time": "2026-06-01T00:00:00Z",
    "end_time": "2026-08-31T23:59:59Z"
  },
  "benefits": [
    {
      "type": "percent_off",
      "percent_off": 25
    }
  ],
  "applies_to": {
    "product_id": "prod_electronics_bundle",
    "variant_ids": ["var_laptop_001", "var_tablet_001"]
  },
  "url": "https://store.example.com/summer-sale"
}

5.4 API Submission

Promotions are upserted via the PATCH endpoint:

PATCH /product_feeds/:feed_id/promotions
Content-Type: application/json
Authorization: Bearer api_key_123

{
  "promotions": [
    {
      "id": "promo_summer_2026",
      "title": "Summer Sale",
      "status": "active",
      "benefits": [
        {
          "type": "percent_off",
          "percent_off": 25
        }
      ]
    }
  ]
}

Matched by id: existing records are updated, non-existing records are created.

5.5 Discounts in Checkout Sessions

When an AI agent creates a Checkout Session, promotion discounts are communicated through the following fields.

Discount Codes

{
  "codes": ["SUMMER25", "WELCOME10"]
}

The codes array contains discount codes provided by the user.

Applied Discounts (AppliedDiscount)

Field	Type	Description
`id`	string	Discount identifier
`code`	string	Discount code
`coupon`	Coupon	Coupon details
`amount`	Price	Discount amount
`automatic`	boolean	Whether automatically applied
`start`	datetime	Start time
`end`	datetime	End time
`method`	enum	`each` (per-item discount) or `across` (total discount)
`priority`	number	Priority (lower number means higher priority)
`allocations`	Allocation[]	Breakdown allocated to each line item

Coupon Object

{
  "coupon": {
    "name": "Summer 25% Off",
    "percent_off": 25,
    "duration": "repeating",
    "max_redemptions": 1000,
    "times_redeemed": 342
  }
}

Coupons support either percent_off (percentage discount) or amount_off (fixed amount discount) modes.

Rejected Discounts (RejectedDiscount)

If a discount code is invalid or not applicable, it appears in the rejected array:

{
  "rejected": [
    {
      "code": "EXPIRED_CODE",
      "reason": "Coupon has expired"
    }
  ]
}

Complete Discount Structure Example

{
  "codes": ["SUMMER25"],
  "applied": [
    {
      "id": "disc_001",
      "code": "SUMMER25",
      "coupon": {
        "name": "Summer Sale",
        "percent_off": 25
      },
      "amount": {
        "amount": 2500,
        "currency": "USD"
      },
      "automatic": false,
      "method": "across",
      "priority": 1,
      "allocations": []
    }
  ],
  "rejected": []
}

5.6 Best Practices

Practice	Description
Use stable promotion IDs	Keep the ID unchanged when updating promotions
Set explicit time ranges	Avoid promotions remaining in active status indefinitely
Update status promptly	Mark expired promotions as `disabled` or `expired`
Test discount calculations	Verify that minor-unit amount calculations are correct
Specify applicable products	Use `applies_to` to precisely control promotion scope
Price consistency	Promotion prices must match actual discounts on your website

Next chapter: Chapter 6: Data Quality Best Practices — ID stability, URL conventions, prohibited content

ACP product feed REST API reference ACP product data quality best practices

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

ACP promotions and discount configuration

Promotions Management

5.1 Promotion Object

Promotion Status

Active Time Range

Product Targeting

5.2 Three Discount Types

Fixed Amount Discount (AmountOffBenefit)

Percentage Discount (PercentOffBenefit)

Free Shipping (FreeShippingBenefit)

5.3 Complete Promotion Example

5.4 API Submission

5.5 Discounts in Checkout Sessions

Discount Codes

Applied Discounts (AppliedDiscount)

Coupon Object

Rejected Discounts (RejectedDiscount)

Complete Discount Structure Example

5.6 Best Practices

​Promotions Management

​5.1 Promotion Object

​Promotion Status

​Active Time Range

​Product Targeting

​5.2 Three Discount Types

​Fixed Amount Discount (AmountOffBenefit)

​Percentage Discount (PercentOffBenefit)

​Free Shipping (FreeShippingBenefit)

​5.3 Complete Promotion Example

​5.4 API Submission

​5.5 Discounts in Checkout Sessions

​Discount Codes

​Applied Discounts (AppliedDiscount)

​Coupon Object

​Rejected Discounts (RejectedDiscount)

​Complete Discount Structure Example

​5.6 Best Practices

Promotions Management

5.1 Promotion Object

Promotion Status

Active Time Range

Product Targeting

5.2 Three Discount Types

Fixed Amount Discount (AmountOffBenefit)

Percentage Discount (PercentOffBenefit)

Free Shipping (FreeShippingBenefit)

5.3 Complete Promotion Example

5.4 API Submission

5.5 Discounts in Checkout Sessions

Discount Codes

Applied Discounts (AppliedDiscount)

Coupon Object

Rejected Discounts (RejectedDiscount)

Complete Discount Structure Example

5.6 Best Practices