اجرای کدهای تخفیف و پروموشن، اجرای کدهای تخفیف و پروموشن

این راهنما، مرجع فنی API و طرحواره‌های بار مفید برای مدیریت کدهای تبلیغاتی و تخفیف‌ها در نسخه 2026-04-08 پروتکل تجارت جهانی (UCP) را ارائه می‌دهد.

قبل از ساخت نقاط پایانی، مطمئن شوید که مرور کلی کدهای تخفیف و تخفیف‌ها را برای مفاهیم سطح بالا، ثابت‌های ریاضی و قوانین مدیریت خطا بررسی کرده‌اید.

کشف

برای دریافت کدهای تخفیف از گوگل، باید پشتیبانی از تخفیف را در پروفایل خود تبلیغ کنید. در نسخه 2026-04-08 ، پلتفرم‌ها قبل از ارسال کدهای تخفیف، بررسی می‌کنند که آیا قابلیت پرداخت تمدید شده است یا خیر.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08",
          "extends": ["dev.ucp.shopping.checkout"],
          "spec": "https://ucp.dev/2026-04-08/specification/discount",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json"
        }
      ]
    }
  }
}

تأثیر بر اقلام خطی و جمع کل

تخفیف‌های اعمال‌شده در فیلدهای اصلی پرداخت با استفاده از دو نوع مجموع مجزا منعکس می‌شوند. اگر تخفیفی allocations داشته باشد که به اقلام خطی اشاره می‌کنند، در items_discount مشارکت می‌کند. تخفیف‌های بدون تخصیص، یا با تخصیص‌هایی به حمل و نقل یا هزینه‌ها، در discount مشارکت می‌کنند.

نوع تخفیف	نوع کل	جایی که منعکس شده است
تخفیف روی هر کالا	items_discount	line_items[].totals[type=items_discount]
تخفیف در سطح سفارش	discount	totals[type=discount]

نسخه مورد نیاز:

برای نسخه 2026-04-08 ، ورودی‌های تخفیف در totals[] و line_items[].totals[] باید از مقادیر منفی برای انعکاس اثر تفریقی خود بر رسید استفاده کنند. مبالغ داخل آرایه‌های discounts.applied و allocations همیشه اعداد صحیح مثبت باقی می‌مانند.

نمونه‌های API برای تبلیغات خودکار اعمال شده

مثال‌های زیر نشان می‌دهند که تخفیف‌ها به صورت خودکار اعمال می‌شوند. فایل‌های درخواست شامل آرایه discounts.codes نیستند، اما پاسخ‌ها شامل "automatic": true و فیلد code حذف می‌کنند.

اعمال خودکار تخفیف در سطح کالا

تخفیف ۱۰ درصدی در کل سایت به طور خودکار برای یک کالای خاص اعمال می‌شود.

نمونه درخواست:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "Sneakers", "price": 10000 },
      "quantity": 1
    }
  ]
}

مثال پاسخ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "Sneakers", "price": 10000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 10000},
        {"type": "items_discount", "amount": -1000},
        {"type": "total", "amount": 9000}
      ]
    }
  ],
  "discounts": {
    "applied": [
      {
        "title": "10% Off Sitewide Sale",
        "amount": 1000,
        "automatic": true,
        "method": "each",
        "allocations": [
          {"path": "$.line_items[0]", "amount": 1000}
        ]
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 9000}
  ]
}

اعمال خودکار تخفیف در سطح سفارش

یک قانون تبلیغاتی (مثلاً «۱۰ دلار تخفیف برای سفارش‌های بالای ۵۰ دلار») که برای کل سفارش اعمال می‌شود، بدون اینکه تخصیص خاصی به هر ردیف از اقلام داشته باشد.

نمونه درخواست:

{
  "line_items": [ ... ]
}

مثال پاسخ:

{
  "line_items": [ ... ],
  "discounts": {
    "applied": [
      {
        "title": "$10 Off Orders Over $50",
        "amount": 1000,
        "automatic": true
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 6000},
    {"type": "discount", "display_text": "Order Promo", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 5000}
  ]
}

نمونه‌های API برای تبلیغات اعمال‌شده توسط کاربر

مثال‌های زیر تخفیف‌هایی را نشان می‌دهند که با وارد کردن یک کد تبلیغاتی توسط کاربر اعمال می‌شوند. درخواست‌های ارسالی شامل کدهای درخواستی هستند و پاسخ‌ها آنها را هنگام تخصیص مبالغ اعمال شده، منعکس می‌کنند.

تخفیف در سطح سفارش

یک تخفیف ثابت روی کل سفارش اعمال می‌شود. نیازی به تخصیص نیست؛ تخفیف روی کل سفارش اعمال می‌شود و type: "discount" استفاده می‌کند.

نمونه درخواست:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10"]
  }
}

مثال پاسخ:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
    {"type": "discount", "display_text": "Order Discount", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 4000}
  ]
}

تخفیف‌های ترکیبی (کالا + سطح سفارش)

این مثال هر دو نوع تخفیف را نشان می‌دهد: تخفیف برای هر کالا (20٪ تخفیف) که به ردیف‌های کالا اختصاص داده می‌شود، و تخفیف ارسال خودکار در سطح سفارش.

نمونه درخواست:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SUMMER20"]
  }
}

مثال پاسخ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "T-Shirt", "price": 2000 },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "items_discount", "amount": -800},
        {"type": "total", "amount": 3200}
      ]
    }
  ],
  "discounts": {
    "codes": ["SUMMER20"],
    "applied": [
      {
        "code": "SUMMER20",
        "title": "Summer Sale 20% Off",
        "amount": 800,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 800}
        ]
      },
      {
        "title": "Free shipping on orders over $30",
        "amount": 599,
        "automatic": true
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 4000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -800},
    {"type": "discount", "display_text": "Order Discounts", "amount": -599},
    {"type": "fulfillment", "display_text": "Shipping", "amount": 0},
    {"type": "total", "display_text": "Total", "amount": 2601}
  ]
}

کد تخفیف رد شده

وقتی کدی نامعتبر است، در codes تکرار می‌شود اما از applied حذف می‌شود. رد شدن کد با استفاده از یک warning در آرایه messages[] اطلاع داده می‌شود.

نمونه درخواست:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"]
  }
}

مثال پاسخ:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
    {"type": "discount", "display_text": "Order Discount", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 4000}
  ],
  "messages": [
    {
      "type": "warning",
      "code": "discount_code_expired",
      "path": "$.discounts.codes[1]",
      "content": "Code 'EXPIRED50' expired on December 1st"
    }
  ]
}

تخفیف‌های انباشته با تخصیص‌ها

تخفیف‌های چندگانه با تفکیک کامل تخصیص اعمال می‌شود.

نکته: فیلدهای priority و method ترتیب محاسبه را تعریف می‌کنند.

نمونه درخواست:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SUMMER20", "EXTRA5"]
  }
}

مثال پاسخ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "T-Shirt", "price": 6000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 6000},
        {"type": "items_discount", "amount": -1500},
        {"type": "total", "amount": 4500}
      ]
    },
    {
      "id": "li_2",
      "item": { "title": "Socks", "price": 4000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "items_discount", "amount": -1000},
        {"type": "total", "amount": 3000}
      ]
    }
  ],
  "discounts": {
    "codes": ["SUMMER20", "EXTRA5"],
    "applied": [
      {
        "code": "SUMMER20",
        "title": "Summer Sale 20% Off",
        "amount": 2000,
        "method": "each",
        "priority": 1,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 1200},
          {"path": "$.line_items[1]", "amount": 800}
        ]
      },
      {
        "code": "EXTRA5",
        "title": "Extra $5 Off",
        "amount": 500,
        "method": "across",
        "priority": 2,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 300},
          {"path": "$.line_items[1]", "amount": 200}
        ]
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -2500},
    {"type": "total", "display_text": "Total", "amount": 7500}
  ]
}

،

این راهنما، مرجع فنی API و طرحواره‌های بار مفید برای مدیریت کدهای تبلیغاتی و تخفیف‌ها در نسخه 2026-04-08 پروتکل تجارت جهانی (UCP) را ارائه می‌دهد.

قبل از ساخت نقاط پایانی، مطمئن شوید که مرور کلی کدهای تخفیف و تخفیف‌ها را برای مفاهیم سطح بالا، ثابت‌های ریاضی و قوانین مدیریت خطا بررسی کرده‌اید.

کشف

برای دریافت کدهای تخفیف از گوگل، باید پشتیبانی از تخفیف را در پروفایل خود تبلیغ کنید. در نسخه 2026-04-08 ، پلتفرم‌ها قبل از ارسال کدهای تخفیف، بررسی می‌کنند که آیا قابلیت پرداخت تمدید شده است یا خیر.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08",
          "extends": ["dev.ucp.shopping.checkout"],
          "spec": "https://ucp.dev/2026-04-08/specification/discount",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json"
        }
      ]
    }
  }
}

تأثیر بر اقلام خطی و جمع کل

تخفیف‌های اعمال‌شده در فیلدهای اصلی پرداخت با استفاده از دو نوع مجموع مجزا منعکس می‌شوند. اگر تخفیفی allocations داشته باشد که به اقلام خطی اشاره می‌کنند، در items_discount مشارکت می‌کند. تخفیف‌های بدون تخصیص، یا با تخصیص‌هایی به حمل و نقل یا هزینه‌ها، در discount مشارکت می‌کنند.

نوع تخفیف	نوع کل	جایی که منعکس شده است
تخفیف روی هر کالا	items_discount	line_items[].totals[type=items_discount]
تخفیف در سطح سفارش	discount	totals[type=discount]

نسخه مورد نیاز:

برای نسخه 2026-04-08 ، ورودی‌های تخفیف در totals[] و line_items[].totals[] باید از مقادیر منفی برای انعکاس اثر تفریقی خود بر رسید استفاده کنند. مبالغ داخل آرایه‌های discounts.applied و allocations همیشه اعداد صحیح مثبت باقی می‌مانند.

نمونه‌های API برای تبلیغات خودکار اعمال شده

مثال‌های زیر نشان می‌دهند که تخفیف‌ها به صورت خودکار اعمال می‌شوند. فایل‌های درخواست شامل آرایه discounts.codes نیستند، اما پاسخ‌ها شامل "automatic": true و فیلد code حذف می‌کنند.

اعمال خودکار تخفیف در سطح کالا

تخفیف ۱۰ درصدی در کل سایت به طور خودکار برای یک کالای خاص اعمال می‌شود.

نمونه درخواست:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "Sneakers", "price": 10000 },
      "quantity": 1
    }
  ]
}

مثال پاسخ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "Sneakers", "price": 10000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 10000},
        {"type": "items_discount", "amount": -1000},
        {"type": "total", "amount": 9000}
      ]
    }
  ],
  "discounts": {
    "applied": [
      {
        "title": "10% Off Sitewide Sale",
        "amount": 1000,
        "automatic": true,
        "method": "each",
        "allocations": [
          {"path": "$.line_items[0]", "amount": 1000}
        ]
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 9000}
  ]
}

اعمال خودکار تخفیف در سطح سفارش

یک قانون تبلیغاتی (مثلاً «۱۰ دلار تخفیف برای سفارش‌های بالای ۵۰ دلار») که برای کل سفارش اعمال می‌شود، بدون اینکه تخصیص خاصی به هر ردیف از اقلام داشته باشد.

نمونه درخواست:

{
  "line_items": [ ... ]
}

مثال پاسخ:

{
  "line_items": [ ... ],
  "discounts": {
    "applied": [
      {
        "title": "$10 Off Orders Over $50",
        "amount": 1000,
        "automatic": true
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 6000},
    {"type": "discount", "display_text": "Order Promo", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 5000}
  ]
}

نمونه‌های API برای تبلیغات اعمال‌شده توسط کاربر

مثال‌های زیر تخفیف‌هایی را نشان می‌دهند که با وارد کردن یک کد تبلیغاتی توسط کاربر اعمال می‌شوند. درخواست‌های ارسالی شامل کدهای درخواستی هستند و پاسخ‌ها آنها را هنگام تخصیص مبالغ اعمال شده، منعکس می‌کنند.

تخفیف در سطح سفارش

یک تخفیف ثابت روی کل سفارش اعمال می‌شود. نیازی به تخصیص نیست؛ تخفیف روی کل سفارش اعمال می‌شود و type: "discount" استفاده می‌کند.

نمونه درخواست:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10"]
  }
}

مثال پاسخ:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
    {"type": "discount", "display_text": "Order Discount", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 4000}
  ]
}

تخفیف‌های ترکیبی (کالا + سطح سفارش)

این مثال هر دو نوع تخفیف را نشان می‌دهد: تخفیف برای هر کالا (20٪ تخفیف) که به ردیف‌های کالا اختصاص داده می‌شود، و تخفیف ارسال خودکار در سطح سفارش.

نمونه درخواست:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SUMMER20"]
  }
}

مثال پاسخ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "T-Shirt", "price": 2000 },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "items_discount", "amount": -800},
        {"type": "total", "amount": 3200}
      ]
    }
  ],
  "discounts": {
    "codes": ["SUMMER20"],
    "applied": [
      {
        "code": "SUMMER20",
        "title": "Summer Sale 20% Off",
        "amount": 800,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 800}
        ]
      },
      {
        "title": "Free shipping on orders over $30",
        "amount": 599,
        "automatic": true
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 4000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -800},
    {"type": "discount", "display_text": "Order Discounts", "amount": -599},
    {"type": "fulfillment", "display_text": "Shipping", "amount": 0},
    {"type": "total", "display_text": "Total", "amount": 2601}
  ]
}

کد تخفیف رد شده

وقتی کدی نامعتبر است، در codes تکرار می‌شود اما از applied حذف می‌شود. رد شدن کد با استفاده از یک warning در آرایه messages[] اطلاع داده می‌شود.

نمونه درخواست:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"]
  }
}

مثال پاسخ:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
    {"type": "discount", "display_text": "Order Discount", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 4000}
  ],
  "messages": [
    {
      "type": "warning",
      "code": "discount_code_expired",
      "path": "$.discounts.codes[1]",
      "content": "Code 'EXPIRED50' expired on December 1st"
    }
  ]
}

تخفیف‌های انباشته با تخصیص‌ها

تخفیف‌های چندگانه با تفکیک کامل تخصیص اعمال می‌شود.

نکته: فیلدهای priority و method ترتیب محاسبه را تعریف می‌کنند.

نمونه درخواست:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SUMMER20", "EXTRA5"]
  }
}

مثال پاسخ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "T-Shirt", "price": 6000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 6000},
        {"type": "items_discount", "amount": -1500},
        {"type": "total", "amount": 4500}
      ]
    },
    {
      "id": "li_2",
      "item": { "title": "Socks", "price": 4000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "items_discount", "amount": -1000},
        {"type": "total", "amount": 3000}
      ]
    }
  ],
  "discounts": {
    "codes": ["SUMMER20", "EXTRA5"],
    "applied": [
      {
        "code": "SUMMER20",
        "title": "Summer Sale 20% Off",
        "amount": 2000,
        "method": "each",
        "priority": 1,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 1200},
          {"path": "$.line_items[1]", "amount": 800}
        ]
      },
      {
        "code": "EXTRA5",
        "title": "Extra $5 Off",
        "amount": 500,
        "method": "across",
        "priority": 2,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 300},
          {"path": "$.line_items[1]", "amount": 200}
        ]
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -2500},
    {"type": "total", "display_text": "Total", "amount": 7500}
  ]
}