Implémentation du cycle de vie des commandes

Ce guide fournit la documentation de référence technique de l'API et les schémas de charge utile nécessaires pour transmettre à Google les informations complètes de l'état des commandes, les événements de traitement et les ajustements à l'aide de webhooks pour la version 2026-01-23 du protocole Universal Commerce Protocol (UCP).

Avant de créer vos points de terminaison, assurez-vous d'avoir consulté la présentation du cycle de vie des commandes pour connaître les concepts généraux, les événements obligatoires et les détails des points de terminaison de webhook.

Authentification et signature des requêtes

Vous pouvez effectuer une signature de clé symétrique à l'aide d'une clé HMAC partagée par Google avec vous.

Vous pouvez également vous reporter aux instructions suivantes pour une signature asymétrique :

  1. Sélectionnez une clé dans le tableau signing_keys du profil UCP.
  2. Créez un JWT dissocié (RFC 7797) sur le corps de la requête à l'aide de la clé sélectionnée.
  3. Incluez le JWT dans l'en-tête Request-Signature.
  4. Incluez l'ID de clé dans la revendication kid de l'en-tête JWT pour permettre au destinataire d'identifier la clé à utiliser pour la validation.

Validation de l'horodatage

Pour déterminer si une mise à jour de commande est antérieure à la dernière version enregistrée (ce qui entraîne le rejet de la mise à jour), Google vérifie l'horodatage à l'aide de la propriété created_time de la charge utile.

Événement de création d'une commande

  • Déclencheur : immédiatement après la confirmation de la commande (status: processing).

Exemple : cet exemple montre une commande créée après qu'un acheteur a effectué le paiement.

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

Événements de traitement

Ces événements sont envoyés dans le tableau fulfillment.events.

Commande expédiée

Lorsque les articles de la commande ont été expédiés. Les champs tracking_number et tracking_url sont obligatoires pour les événements d'expédition, car ils sont nécessaires pour regrouper précisément les articles sur la page "Mes commandes".

Commande livrée

Lorsque les articles de la commande ont été livrés.

Exemple (shipped et delivered) : cet exemple montre une mise à jour de la commande après l'expédition et la livraison de l'article.

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

Exemples de commandes comportant plusieurs articles

Les exemples suivants montrent comment structurer les informations sur les commandes comportant plusieurs articles et les livraisons fractionnées. Pour en savoir plus sur la façon dont les états des colis sont déterminés, consultez Comment l'état des colis est déterminé.

Commande de plusieurs articles, livraison dans un même colis

Cet exemple montre une mise à jour de commande pour un seul colis contenant plusieurs articles. Tous les éléments sont regroupés dans un seul événement shipped partageant le même numéro de suivi.

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

Commande de plusieurs articles, livraison fractionnée

Cet exemple montre une mise à jour de commande pour les livraisons fractionnées. Il existe plusieurs événements shipped, chacun faisant référence à l'élément line_items spécifique de ce package, avec des numéros de suivi distincts. Étant donné que chaque colis représente un engagement de traitement distinct (par exemple, des vitesses et des coûts différents lors d'un paiement groupé), les attentes (expectations) sont également divisées.

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

Exemples d'événements d'ajustement

Les exemples suivants montrent comment structurer les informations sur les remboursements, les retours et les annulations. Pour obtenir la liste des événements acceptés et leur définition, consultez Événements d'ajustement dans la présentation du cycle de vie des commandes.

Annulation et remboursement d'une commande

Cet exemple montre une commande pour laquelle l'article a été annulé et remboursé peu de temps après que la commande a été passée.

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

Retour et remboursement de commande

Cet exemple montre une commande pour laquelle l'article a été expédié, livré, puis retourné et remboursé.

{
  "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"
}
Précédent
API pour le paiement natif
Suivant
Signaux de risque