הטמעה של קודי שובר והנחות

במדריך הזה מפורטים קודי ה-API הטכניים וסכימות המטען הייעודי (payload) לטיפול בקודי מבצע ובהנחות בגרסה 2026-04-08 של Universal Commerce Protocol‏ (UCP).

לפני שיוצרים את נקודות הקצה, חשוב לעיין בסקירה הכללית על קודי שוברים והנחות כדי להבין את המושגים ברמה גבוהה, את האינווריאנטים המתמטיים ואת כללי הטיפול בשגיאות.

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

ההשפעה על פריטים ועל סכומים כוללים

ההנחות שחלות על המוצרים משתקפות בשדות הליבה של דף התשלום באמצעות שני סוגים שונים של סכומים כוללים. אם הנחה 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}
  ]
}

הנחה ברמת ההזמנה שמוחלת באופן אוטומטי

כלל מבצע (לדוגמה, "הנחה של 40 ש"ח על הזמנות מעל 200 ש"ח") שחל על ההזמנה כולה ללא הקצאות ספציפיות של פריטים.

דוגמה לבקשה:

{
  "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 של מבצעים שמופעלים על ידי המשתמש

בדוגמאות הבאות אפשר לראות הנחות שמופעלות כשמשתמש מזין קוד שובר. מטענים ייעודיים (payloads) של בקשות כוללים את הקודים המבוקשים, והתגובות משקפות אותם בחזרה תוך הקצאת הסכומים שהוחלו.

הנחה ברמת ההזמנה

הנחה קבועה שחלה על סכום ההזמנה הכולל. לא צריך להקצות את ההנחה, כי היא חלה על ההזמנה כולה ומשתמשת ב-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}
  ]
}