এই পৃষ্ঠাটি Cloud Translation API অনুবাদ করেছে।

অর্ডার লাইফসাইকেল বাস্তবায়ন, অর্ডার লাইফসাইকেল বাস্তবায়ন

এই নির্দেশিকাটি ইউনিভার্সাল কমার্স প্রোটোকল (UCP)-এর 2026-01-23 সংস্করণের জন্য ওয়েবহুক ব্যবহার করে গুগল-এ সম্পূর্ণ অর্ডার স্ট্যাটাস আপডেট, ফুলফিলমেন্ট ইভেন্ট এবং পরিবর্তনসমূহ পাঠানোর প্রযুক্তিগত এপিআই রেফারেন্স ও পেলোড স্কিমা প্রদান করে।

আপনার এন্ডপয়েন্টগুলো তৈরি করার আগে, উচ্চ-স্তরের ধারণা, বাধ্যতামূলক ইভেন্ট এবং ওয়েবহুক এন্ডপয়েন্টের বিবরণ জানার জন্য অর্ডার লাইফসাইকেল ওভারভিউটি পর্যালোচনা করে নিন।

প্রমাণীকরণ এবং অনুরোধ স্বাক্ষর

গুগলের দেওয়া HMAC কী ব্যবহার করে আপনি সিমেট্রিক কী সাইনিং করতে পারেন।

অথবা, একটি অপ্রতিসম স্বাক্ষরের জন্য আপনি নিম্নলিখিত নির্দেশাবলী অনুসরণ করতে পারেন:

UCP প্রোফাইলে থাকা signing_keys অ্যারে থেকে একটি কী নির্বাচন করুন।
নির্বাচিত কী ব্যবহার করে অনুরোধের মূল অংশের উপর একটি বিচ্ছিন্ন JWT ( RFC 7797 ) তৈরি করুন।
Request-Signature হেডারে JWT অন্তর্ভুক্ত করুন।
JWT হেডারের kid claim-এ কী ID অন্তর্ভুক্ত করুন, যাতে প্রাপক যাচাইকরণের জন্য কোন কী ব্যবহার করতে হবে তা শনাক্ত করতে পারে।

টাইমস্ট্যাম্প যাচাইকরণ

কোনো অর্ডার আপডেট সর্বশেষ রেকর্ড করা আপডেটের চেয়ে পুরোনো কিনা (যা অর্ডার আপডেট প্রত্যাখ্যানের কারণ হয়) তা মূল্যায়ন করার সময়, গুগল পেলোডে থাকা created_time প্রপার্টি ব্যবহার করে টাইমস্ট্যাম্পটি যাচাই করে।

অর্ডার তৈরি ইভেন্ট

ট্রিগার: অর্ডার নিশ্চিত হওয়ার ঠিক পরেই ( status: processing )।

উদাহরণ: এই উদাহরণটি একজন ক্রেতা চেকআউট সম্পন্ন করার পর তৈরি হওয়া একটি অর্ডার দেখাচ্ছে।

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "created_time": "2026-03-23T19:00:00Z",
   // Full line items must be included
  "line_items": [
    {
      "id": "line_1",
      "item":
        {
          "id": "product_123",
          "title": "Running Shoes",
          "price": 10000
        },
      "quantity": { "total": 1, "fulfilled": 0 },
      "totals": [
        {"type": "subtotal", "amount": 10000},
        {"type": "total", "amount": 10000}
      ],
      // The status of a line item must match total and fulfilled quantities (e.g., total 1, fulfilled 0 -> status: processing).
      "status": "processing"
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 10000},
    {"type": "total", "amount": 10000}
  ],
  "fulfillment": {
    "expectations": [
      {
        "id": "exp_1",
        "line_items": [{ "id": "line_1", "quantity": 1 }],
        "method_type": "shipping",
        "destination": {
          "first_name": "Alice",
          "last_name": "Example",
          "street_address": "123 Main St",
          "address_locality": "Austin",
          "address_region": "TX",
          "address_country": "US",
          "postal_code": "78701"
        },
        "description": "Arrives in 2-3 business days",
        "fulfillable_on": "now"
      }
    ]
  },
  "permalink_url": "https://merchant.example.com/orders/789"
}

পরিপূর্ণতার ইভেন্ট

এই ইভেন্টগুলো fulfillment.events অ্যারের অংশ হিসেবে পাঠানো হয়।

অর্ডার পাঠানো হয়েছে

অর্ডারের আইটেমগুলো পাঠানো হয়ে গেলে। 'শিপড' ইভেন্টের জন্য tracking_number এবং tracking_url ফিল্ডগুলো আবশ্যক, কারণ 'আমার অর্ডার' পেজে আইটেমগুলোকে সঠিকভাবে গ্রুপ করার জন্য এগুলো প্রয়োজন।

অর্ডার ডেলিভারি করা হয়েছে

অর্ডারের পণ্যগুলো ডেলিভারি হয়ে গেলে

উদাহরণ ( shipped ও delivered ): এই উদাহরণটি দেখায় যে পণ্যটি প্রেরণ এবং বিতরণ করার পরে কীভাবে অর্ডার আপডেট করা হয়।

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_01",
  "checkout_id": "checkout_01",
  "created_time": "2026-03-23T19:00:00Z",
  "line_items": [
    {
      "id": "line_1",
      "item":
        {
          "id": "product_123",
          "title": "Running Shoes",
          "price": 10000
        },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "amount": 10000},
        {"type": "total", "amount": 10000}
      ],
      "status": "fulfilled"
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 10000},
    {"type": "total", "amount": 10000}
  ],
  // Updated fulfillment details.
  "fulfillment": {
    "events": [
      {
        "id": "fulfill_evt_1",
        "occurred_at": "2026-02-08T10:30:00Z",
        "type": "shipped",
        "line_items": [{ "id": "line_1", "quantity": 1 }],
        "tracking_number": "123456789",
        "tracking_url": "https://fedex.com/track/123456789",
        "carrier": "FedEx",
        "description": "Shipping departed from warehouse"
      },
      {
        "id": "fulfill_evt_2",
        "occurred_at": "2026-02-10T14:00:00Z",
        "type": "delivered",
        "line_items": [{ "id": "line_1", "quantity": 1 }],
        "tracking_number": "123456789",
        "tracking_url": "https://fedex.com/track/123456789",
        "carrier": "FedEx",
        "description": "Package delivered"
      }
    ],
    "expectations": [{ "...": "..." }]
  },
  "permalink_url": "https://merchant.example.com/orders/123"
}

একাধিক আইটেমের অর্ডারের উদাহরণ

নিম্নলিখিত উদাহরণগুলি দেখায় কিভাবে একাধিক আইটেমের অর্ডার এবং বিভক্ত চালানের জন্য আপডেটগুলি গঠন করতে হয়। প্যাকেজের স্ট্যাটাস কীভাবে নির্ধারণ করা হয় তার নিয়মের জন্য, "প্যাকেজের স্ট্যাটাস কীভাবে নির্ধারিত হয়" দেখুন।

একাধিক পণ্যের অর্ডার, একই প্যাকেজে ডেলিভারি

এই উদাহরণটি একাধিক আইটেম সম্বলিত একটি একক প্যাকেজের অর্ডার আপডেট দেখাচ্ছে। সমস্ত লাইন আইটেম একই ট্র্যাকিং নম্বর ব্যবহার করে একটি একক shipped ইভেন্টের অধীনে একত্রিত করা হয়েছে।

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_multi_01",
  "checkout_id": "checkout_multi_01",
  "created_time": "2026-02-07T09:00:00Z",
  "line_items": [
    {
      "id": "line_1",
      "item": { "id": "product_1", "title": "Item 1", "price": 5000 },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ],
      "status": "fulfilled"
    },
    {
      "id": "line_2",
      "item": { "id": "product_2", "title": "Item 2", "price": 5000 },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ],
      "status": "fulfilled"
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 10000},
    {"type": "fee", "amount": 500},
    {"type": "total", "amount": 10500}
  ],
  "fulfillment": {
    "expectations": [
      {
        "id": "exp_1",
        "line_items": [
          { "id": "line_1", "quantity": 1 },
          { "id": "line_2", "quantity": 1 }
        ],
        "method_type": "shipping",
        "destination": {
          "first_name": "Alice",
          "last_name": "Example",
          "street_address": "123 Main St",
          "address_locality": "Austin",
          "address_region": "TX",
          "address_country": "US",
          "postal_code": "78701"
        },
        "description": "Standard Shipping",
        "fulfillable_on": "now"
      }
    ],
    "events": [
      {
        "id": "fulfill_evt_1",
        "occurred_at": "2026-02-08T10:30:00Z",
        "type": "shipped",
        "line_items": [
          { "id": "line_1", "quantity": 1 },
          { "id": "line_2", "quantity": 1 }
        ],
        "tracking_number": "123456789",
        "tracking_url": "https://fedex.com/track/123456789",
        "carrier": "FedEx",
        "description": "Both items shipped together"
      }
    ]
  },
  "permalink_url": "https://merchant.example.com/orders/456"
}

একাধিক আইটেমের অর্ডার, বিভক্ত চালান

এই উদাহরণটি বিভক্ত চালানের জন্য একটি অর্ডার আপডেট দেখাচ্ছে। এখানে একাধিক shipped ইভেন্ট রয়েছে, যার প্রতিটি সংশ্লিষ্ট প্যাকেজের মধ্যে থাকা নির্দিষ্ট line_items নির্দেশ করে এবং সেগুলোর আলাদা ট্র্যাকিং নম্বর থাকে। যেহেতু প্রতিটি প্যাকেজ একটি স্বতন্ত্র ফুলফিলমেন্ট প্রতিশ্রুতিকে প্রতিনিধিত্ব করে (যেমন, একটি মাল্টি-গ্রুপ চেকআউট থেকে ভিন্ন গতি এবং খরচ), তাই expectations বিভক্ত করা হয়।

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_multi_02",
  "checkout_id": "checkout_multi_02",
  "created_time": "2026-02-07T09:00:00Z",
  "line_items": [
    {
      "id": "line_1",
      "item": { "id": "product_1", "title": "Item 1", "price": 5000 },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ],
      "status": "fulfilled"
    },
    {
      "id": "line_2",
      "item": { "id": "product_2", "title": "Item 2", "price": 5000 },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ],
      "status": "fulfilled"
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 10000},
    {"type": "fee", "amount": 1500},
    {"type": "total", "amount": 11500}
  ],
  "fulfillment": {
    "expectations": [
      {
        "id": "exp_1",
        "line_items": [{ "id": "line_1", "quantity": 1 }],
        "method_type": "shipping",
        "destination": {
          "first_name": "Alice",
          "last_name": "Example",
          "street_address": "123 Main St",
          "address_locality": "Austin",
          "address_region": "TX",
          "address_country": "US",
          "postal_code": "78701"
        },
        "description": "Standard Shipping",
        "fulfillable_on": "now"
      },
      {
        "id": "exp_2",
        "line_items": [{ "id": "line_2", "quantity": 1 }],
        "method_type": "shipping",
        "destination": {
          "first_name": "Alice",
          "last_name": "Example",
          "street_address": "123 Main St",
          "address_locality": "Austin",
          "address_region": "TX",
          "address_country": "US",
          "postal_code": "78701"
        },
        "description": "Express Shipping",
        "fulfillable_on": "now"
      }
    ],
    "events": [
      {
        "id": "fulfill_evt_1",
        "occurred_at": "2026-02-08T10:30:00Z",
        "type": "shipped",
        "line_items": [{ "id": "line_1", "quantity": 1 }],
        "tracking_number": "PKG1_TRACKING",
        "tracking_url": "https://fedex.com/track/PKG1_TRACKING",
        "carrier": "FedEx",
        "description": "First item shipped in package 1"
      },
      {
        "id": "fulfill_evt_2",
        "occurred_at": "2026-02-09T14:00:00Z",
        "type": "shipped",
        "line_items": [{ "id": "line_2", "quantity": 1 }],
        "tracking_number": "PKG2_TRACKING",
        "tracking_url": "https://fedex.com/track/PKG2_TRACKING",
        "carrier": "FedEx",
        "description": "Second item shipped in package 2"
      }
    ]
  },
  "permalink_url": "https://merchant.example.com/orders/457"
}

সমন্বয় ইভেন্টের উদাহরণ

নিম্নলিখিত উদাহরণগুলি রিফান্ড, রিটার্ন এবং ক্যান্সেলেশনের জন্য আপডেটগুলি কীভাবে গঠন করতে হয় তা প্রদর্শন করে। সমর্থিত ইভেন্টগুলির তালিকা এবং তাদের সংজ্ঞার জন্য, অর্ডার লাইফসাইকেল ওভারভিউতে অ্যাডজাস্টমেন্ট ইভেন্টগুলি দেখুন।

অর্ডার বাতিল এবং ফেরত

এই উদাহরণে এমন একটি অর্ডার দেখানো হয়েছে, যেখানে অর্ডারটি দেওয়ার অল্প সময়ের মধ্যেই পণ্যটি বাতিল করে অর্থ ফেরত দেওয়া হয়েছিল।

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_02",
  "checkout_id": "checkout_02",
  "created_time": "2026-03-23T19:00:00Z",
  "line_items": [
    {
      "id": "line_2",
      "item": {
        "id": "product_456",
        "title": "Smart Watch",
        "price": 29900
      },
      "quantity": { "total": 1, "fulfilled": 0 },
      "totals": [
        {"type": "subtotal", "amount": 29900},
        {"type": "tax", "amount": 2400},
        {"type": "total", "amount": 32300}
      ],
      "status": "processing"
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 29900},
    {"type": "tax", "amount": 2400},
    {"type": "total", "amount": 32300}
  ],
  "adjustments": [
    {
      "id": "adj_cancel_1",
      "type": "cancellation",
      "description": "Customer changed mind",
      "line_items": [{ "id": "line_2", "quantity": 1 }],
      "occurred_at": "2026-02-09T11:00:00Z",
      "status": "completed"
    },
    {
      "id": "adj_refund_1",
      "type": "refund",
      "description": "Refund for cancelled item",
      "line_items": [{ "id": "line_2", "quantity": 1 }],
      "amount": 32300,
      "occurred_at": "2026-02-09T11:05:00Z",
      "status": "completed"
    }
  ],
  "permalink_url": "https://merchant.example.com/orders/12345"
}

অর্ডার ফেরত এবং রিফান্ড

এই উদাহরণটিতে এমন একটি অর্ডার দেখানো হয়েছে, যেখানে পণ্যটি পাঠানো, ডেলিভারি করা এবং তারপর ফেরত নিয়ে টাকা ফেরত দেওয়া হয়েছে।

{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.order": [{"version": "2026-01-23"}]
    }
  },
  "id": "order_03",
  "checkout_id": "checkout_03",
  "created_time": "2026-03-23T19:00:00Z",
  "line_items": [
    {
      "id": "line_3",
      "item": {
        "id": "product_789",
        "title": "Wireless Earbuds",
        "price": 14900
      },
      "quantity": { "total": 1, "fulfilled": 1 },
      "totals": [
        {"type": "subtotal", "amount": 14900},
        {"type": "tax", "amount": 1200},
        {"type": "total", "amount": 16100}
      ],
      "status": "fulfilled"
    }
  ],
  "totals": [
    {"type": "subtotal", "amount": 14900},
    {"type": "tax", "amount": 1200},
    {"type": "total", "amount": 16100}
  ],
  "fulfillment": {
    "events": [
      {
        "id": "fulfill_evt_1",
        "occurred_at": "2026-02-05T09:00:00Z",
        "type": "shipped",
        "line_items": [{ "id": "line_3", "quantity": 1 }],
        "tracking_number": "987654321",
        "tracking_url": "https://fedex.com/track/987654321",
        "carrier": "FedEx",
        "description": "Item shipped"
      },
      {
        "id": "fulfill_evt_2",
        "occurred_at": "2026-02-07T16:00:00Z",
        "type": "delivered",
        "line_items": [{ "id": "line_3", "quantity": 1 }],
        "tracking_number": "987654321",
        "tracking_url": "https://fedex.com/track/987654321",
        "carrier": "FedEx",
        "description": "Item delivered"
      },
      {
        "id": "fulfill_evt_3",
        "occurred_at": "2026-02-09T09:00:00Z",
        "type": "returned",
        "line_items": [{ "id": "line_3", "quantity": 1 }],
        "tracking_number": "987654321",
        "tracking_url": "https://fedex.com/track/987654321",
        "carrier": "FedEx",
        "description": "Item returned"
      }
    ],
    "expectations": [{ "...": "..." }]
  },
  "adjustments": [
    {
      "id": "adj_return_1",
      "type": "return",
      "description": "Item not compatible",
      "line_items": [{ "id": "line_3", "quantity": 1 }],
      "occurred_at": "2026-02-09T09:00:00Z",
      "status": "completed"
    },
    {
      "id": "adj_refund_2",
      "type": "refund",
      "description": "Refund for returned item",
      "line_items": [{ "id": "line_3", "quantity": 1 }],
      "amount": 16100,
      "occurred_at": "2026-02-10T10:00:00Z",
      "status": "completed"
    }
  ],
  "permalink_url": "https://merchant.example.com/orders/67890"
}