การติดตั้งใช้งานรหัสโปรโมชันและส่วนลด

คู่มือนี้มีข้อมูลอ้างอิงทางเทคนิคของ API และสคีมาเพย์โหลดสำหรับการจัดการรหัสโปรโมชันและส่วนลดใน Universal Commerce Protocol (UCP) เวอร์ชัน 2026-04-08

ก่อนสร้างปลายทาง โปรดอ่านภาพรวมของ รหัสโปรโมชันและส่วนลดเพื่อทำความเข้าใจ แนวคิดระดับสูง ตัวแปรทางคณิตศาสตร์ และกฎการจัดการข้อผิดพลาด

Discovery

หากต้องการรับรหัสส่วนลดจาก Google คุณต้องโฆษณาการรองรับส่วนลดในโปรไฟล์ ในเวอร์ชัน 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"
        }
      ]
    }
  }
}

ผลกระทบต่อรายการโฆษณาและยอดรวม

ส่วนลดที่ใช้จะแสดงในช่องการชำระเงินหลักโดยใช้ยอดรวม 2 ประเภทที่แตกต่างกัน หากส่วนลดมี 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

ส่วนลดระดับสินค้าที่ใช้โดยอัตโนมัติ

ส่วนลด 10% ทั่วทั้งเว็บไซต์ที่ใช้กับรายการโฆษณาที่เฉพาะเจาะจงโดยอัตโนมัติ

ตัวอย่างคำขอ:

{
  "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}
  ]
}

ส่วนลดระดับคำสั่งซื้อที่ใช้โดยอัตโนมัติ

กฎโปรโมชัน (เช่น ส่วนลด $10 สำหรับคำสั่งซื้อที่มีมูลค่ามากกว่า $50) ที่ใช้กับคำสั่งซื้อทั้งหมดโดยไม่มีการจัดสรรรายการโฆษณาที่เฉพาะเจาะจง

ตัวอย่างคำขอ:

{
  "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}
  ]
}

ส่วนลดแบบผสม (ระดับสินค้า + คำสั่งซื้อ)

ตัวอย่างนี้แสดงส่วนลดทั้ง 2 ประเภท ได้แก่ ส่วนลดต่อสินค้า (ลด 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}
  ]
}