Please note the Buy on Google program in France will be ending on 7 Dec 2021.

Order Returns

Présentation

Vous pouvez utiliser les méthodes suivantes de la ressource orderreturns version 2.1 pour gérer vos retours :

orderreturns.list pour afficher la liste de vos retours
orderreturns.get pour afficher un retour spécifique
orderreturns.acknowledge pour accuser réception d'un retour
orderreturns.createorderreturn pour créer un retour
orderreturns.labels.create pour importer une étiquette de retour
orderreturns.process pour traiter ou refuser un retour

Voici une présentation de la procédure de retour :

Voici des explications sur les méthodes orderreturns :

Méthodes

orderreturns inclut les méthodes suivantes :

orderreturns.list

Vous pouvez utiliser orderreturns.list pour afficher les retours en fonction de paramètres de requête facultatifs. Cette méthode fournit une valeur orderReturnId unique pour chaque commande (Order). Vous pouvez utiliser orderReturnId en tant que returnId pour appeler la méthode get.

Voici un exemple d'URL :

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns

Voici un exemple d'URL sandbox :

GET https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns

Voici un exemple de réponse de orderreturns.list avec deux retours de commandes. Leurs valeurs orderId sont TEST-8984-80-0722 et TEST-4329-83-8262.


{
  "kind": "content#orderreturnsListResponse",
  "resources": [
    {
      "orderReturnId": "LSYJTDCD7NCZEYE",
      "orderId": "TEST-8984-80-0722",
      "creationDate": "2020-02-11T17:24:13Z",
      "returnShipments": [
        {
          "shipmentId": "LSYJTDCD7NCZEYE",
          "state": "new",
          "creationDate": "2020-02-11T17:24:13Z",
          "shipmentTrackingInfos": [
            {
              "carrier": "deliv",
              "trackingNumber": "tracking_number_idLSYJTDCD7NCZEYE"
            }
          ],
          "returnMethodType": "byMail"
        }
      ],
      "returnItems": [
        {
          "itemId": "LKGJTDCD7NCZEYE",
          "returnItemId": "L2ZJTDCD7NCZEYE",
          "returnShipmentIds": [
            "LSYJTDCD7NCZEYE"
          ],
          "product": {
            "id": "online:en:US:156d6ab2-ed9d-4009-8d01-93cf9a62f54f",
            "offerId": "156d6ab2-ed9d-4009-8d01-93cf9a62f54f",
            "targetCountry": "US",
            "contentLanguage": "en",
            "price": {
              "value": "70.00",
              "currency": "USD"
            },
            "title": "Google Chromecast",
            "gtin": "00811571013579",
            "brand": "Google",
            "mpn": "H2G2-42",
            "condition": "new",
            "imageLink": "http://www.gstatic.com/shopping-content-api/product_images/chromecast.jpg",
            "shownImage": "https://encrypted-tbn1.gstatic.com/shopping?q=tbn:ANd9GcQnZBrlSh95-rICAk"
          },
          "state": "new",
          "customerReturnReason": {
            "reasonCode": "changedMind"
          },
          "refundableAmount": {
            "priceAmount": {
              "value": "70.00",
              "currency": "USD"
            },
            "taxAmount": {
              "value": "0.00",
              "currency": "USD"
            }
          }
        }
      ],
      "returnPricingInfo": {
        "refundableItemsTotalAmount": {
          "priceAmount": {
            "value": "70.00",
            "currency": "USD"
          },
          "taxAmount": {
            "value": "0.00",
            "currency": "USD"
          }
        },
        "refundableShippingAmount": {
          "priceAmount": {
            "value": "20.00",
            "currency": "USD"
          },
          "taxAmount": {
            "value": "0.00",
            "currency": "USD"
          }
        }
      }
    },
    {
      "orderReturnId": "L2GJTDCD7NCZEYE",
      "orderId": "TEST-4329-83-8262",
      "creationDate": "2020-02-11T17:24:11Z",
      "returnShipments": [
        {
          "shipmentId": "L2GJTDCD7NCZEYE",
          "state": "new",
          "creationDate": "2020-02-11T17:24:11Z",
          "shipmentTrackingInfos": [
            {
              "carrier": "deliv",
              "trackingNumber": "tracking_number_idL2GJTDCD7NCZEYE"
            }
          ],
          "returnMethodType": "byMail"
        }
      ],
      "returnItems": [
        {
          "itemId": "LSHJTDCD7NCZEYE",
          "returnItemId": "LCHJTDCD7NCZEYE",
          "returnShipmentIds": [
            "L2GJTDCD7NCZEYE"
          ],
          "product": {
            "id": "online:en:US:f37b9d95-fbc5-46be-ad63-c49fbf1f29b2",
            "offerId": "f37b9d95-fbc5-46be-ad63-c49fbf1f29b2",
            "targetCountry": "US",
            "contentLanguage": "en",
            "price": {
              "value": "70.00",
              "currency": "USD"
            },
            "title": "Google Chromecast",
            "gtin": "00811571013579",
            "brand": "Google",
            "mpn": "H2G2-42",
            "condition": "new",
            "imageLink": "http://www.gstatic.com/shopping-content-api/product_images/chromecast.jpg",
            "shownImage": "https://encrypted-tbn1.gstatic.com/shopping?q=tbn:ANd9GcQnZBrlc&usqp=CAk"
          },
          "state": "new",
          "customerReturnReason": {
            "reasonCode": "changedMind"
          },
          "refundableAmount": {
            "priceAmount": {
              "value": "70.00",
              "currency": "USD"
            },
            "taxAmount": {
              "value": "0.00",
              "currency": "USD"
            }
          }
        }
      ],
      "returnPricingInfo": {
        "refundableItemsTotalAmount": {
          "priceAmount": {
            "value": "70.00",
            "currency": "USD"
          },
          "taxAmount": {
            "value": "0.00",
            "currency": "USD"
          }
        },
        "refundableShippingAmount": {
          "priceAmount": {
            "value": "20.00",
            "currency": "USD"
          },
          "taxAmount": {
            "value": "0.00",
            "currency": "USD"
          }
        }
      }
    }
  ]
}

orderreturns.get

Vous pouvez utiliser orderreturns.get pour afficher un retour individuel basé sur la valeur returnId. Pour trouver la valeur returnId, utilisez la méthode orderreturns.list afin d'obtenir la valeur orderReturnId d'une commande en production, ou enregistrez la valeur returnId renvoyée lors de la création d'un retour test avec l'appel createtestreturn exécuté en mode sandbox.

Voici un exemple d'URL :

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/returnId

Voici un exemple d'URL sandbox :

GET https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId

Voici un exemple de réponse avec deux articles retournés pour orderId: TEST-8984-80-0722, qui ont été renvoyés lors de l'appel orderreturns.list ci-dessus.

{
  "kind": "content#orderreturnsGetResponse",
  "resources":
    {
      "orderReturnId": "LSYJTDCD7NCZEYE",
      "orderId": "TEST-8984-80-0722",
      "creationDate": "2020-02-11T17:24:13Z",
      "returnShipments": [
        {
          "shipmentId": "LSYJTDCD7NCZEYE",
          "state": "new",
          "creationDate": "2020-02-11T17:24:13Z",
          "shipmentTrackingInfos": [
            {
              "carrier": "deliv",
              "trackingNumber": "tracking_number_idLSYJTDCD7NCZEYE"
            }
          ],
          "returnMethodType": "byMail"
        }
      ],
      "returnItems": [
        {
          "itemId": "LKGJTDCD7NCZEYE",
          "returnItemId": "L2ZJTDCD7NCZEYE",
          "returnShipmentIds": [
            "LSYJTDCD7NCZEYE"
          ],
          "product": {
            "id": "online:en:US:156d6ab2-ed9d-4009-8d01-93cf9a62f54f",
            "offerId": "156d6ab2-ed9d-4009-8d01-93cf9a62f54f",
            "targetCountry": "US",
            "contentLanguage": "en",
            "price": {
              "value": "70.00",
              "currency": "USD"
            },
            "title": "Google Chromecast",
            "gtin": "00811571013579",
            "brand": "Google",
            "mpn": "H2G2-42",
            "condition": "new",
            "imageLink": "http://www.gstatic.com/shopping-content-api/product_images/chromecast.jpg",
            "shownImage": "https://encrypted-tbn1.gstatic.com/shopping?q=tbnZ6ibvjDsPWzlmO&usqp=CAk"
          },
          "state": "new",
          "customerReturnReason": {
            "reasonCode": "changedMind"
          },
          "refundableAmount": {
            "priceAmount": {
              "value": "70.00",
              "currency": "USD"
            },
            "taxAmount": {
              "value": "0.00",
              "currency": "USD"
            }
          }
        }
      ],
      "returnPricingInfo": {
        "refundableItemsTotalAmount": {
          "priceAmount": {
            "value": "70.00",
            "currency": "USD"
          },
          "taxAmount": {
            "value": "0.00",
            "currency": "USD"
          }
        },
        "refundableShippingAmount": {
          "priceAmount": {
            "value": "20.00",
            "currency": "USD"
          },
          "taxAmount": {
            "value": "0.00",
            "currency": "USD"
          }
        }
      }
    }
  }

orderreturns.acknowledge

Vous pouvez utiliser orderreturns.acknowledge pour accuser réception d'un retour et définir l'état de acknowledged sur True. Vous pouvez ensuite appeler orderreturns.list pour afficher la liste des derniers retours, filtrés en fonction du paramètre ack.

Voici un exemple d'URL :

POST
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/returnId/acknowledge

Voici un exemple d'URL sandbox :

POST
https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId/acknowledge

Voici un exemple de requête :

{
  "operationId": "ack_op_1"
}

Voici un exemple de réponse :

{
  "kind": "content#orderreturnsAcknowledgeResponse",
  "executionStatus": "executed"
}

orderreturns.createorderreturn

Vous pouvez utiliser orderreturns.createorderreturn pour créer un retour. Vous pouvez définir returnShipmentType sur l'une des valeurs suivantes :

inStore : pour les articles retournés en magasin
byMail : pour les articles retournés par voie postale

Voici un exemple d'URL :

POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/createorderreturn

Voici un exemple d'URL sandbox :

POST https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/createorderreturn

Voici un exemple de requête :

{
  "orderId": "TEST-8984-80-0722",
  "operationId": "operation-uuid-1234",
  "returnMethodType": "inStore",
  "lineItems": [
    {
      "lineItemId": "LKGJTDCD7NCZEYE",
      "quantity": 3
    }
  ],
}

Voici un exemple de réponse :

{
  "kind": "content#orderreturnsCreateorderreturnResponse",
  "executionStatus": "executed",
  "merchantOrderReturn": Object([MerchantOrderReturn](/shopping-content/reference/rest/v2.1/MerchantOrderReturn))
}

orderreturns.process

Vous pouvez utiliser orderreturns.process pour refuser ou traiter un retour.

Le champ paymentType de orderreturns.process peut avoir l'une des valeurs suivantes :

originalFop : remboursement sur le mode de paiement initialement utilisé
cash : remboursement en espèces
credit : remboursement sous forme de crédit en magasin

Remboursements totaux

Vous pouvez effectuer un remboursement total sur le mode de paiement initial en définissant paymentType sur originalFop. Si vous souhaitez rembourser la commande sur un mode de paiement différent de celui d'origine, vous devez utiliser partialRefund.

Pour en savoir plus, consultez la section Retours en magasin.

Voici un exemple de remboursement total en cas d'annulation de la part du client : "returnRefundReason": "customerCanceled".

Voici un exemple d'URL :

POST
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/returnId/process

Voici un exemple d'URL sandbox :

POST
https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId/process

Voici un exemple de requête :

{
  "operationId": "process_op_1",
  "refundShippingFee": {
    "fullRefund": true,
    "reasonText": "canceled",
    "returnRefundReason": "customerCanceled"
  },
  "returnItems": [
    {
      "refund": {
        "fullRefund": true,
        "reasonText": "canceled",
        "returnRefundReason": "customerCanceled"
      },
      "returnItemId": "LCFJTDCD7NCZEYE"
    }
  ]
}

Voici un exemple de réponse :

{
  "kind": "content#orderreturnsProcessResponse",
  "executionStatus": "executed"
}

Remboursements partiels

Vous pouvez utiliser les remboursements partiels pour rembourser un montant spécifique ou émettre un remboursement total vers un mode de paiement différent de celui initialement utilisé pour régler la commande.

Voici un exemple de requête de remboursement partiel en cas d'annulation de la part du client :

{
  "operationId": "process_op_1",
  "refundShippingFee": {
    "fullRefund": true,
    "reasonText": "canceled",
    "returnRefundReason": "customerCanceled"
  },
  "returnItems": [
    {
      "refund": {
        "partialRefund": {
          "priceAmount": {
            "currency": "USD",
            "value": "20"
          },
          "taxAmount": {
            "currency": "USD",
            "value": "0"
          }
        },
        "reasonText": "canceled",
        "returnRefundReason": "customerCanceled"
      },
      "returnItemId": "LCFJTDCD7NCZEYE"
    }
  ]
}

Voici un exemple de réponse :

{
  "kind": "content#orderreturnsProcessResponse",
  "executionStatus": "executed"
}

Retours en magasin

Si vous disposez de magasins physiques, vos clients peuvent effectuer un retour en magasin et recevoir un remboursement sous les formes suivantes :

Sur le mode de paiement d'origine
En espèces
Crédit en magasin

Pour traiter un retour en magasin, recherchez le retour dans votre compte avec orderId et orderreturns.list. Si le retour n'apparaît pas dans votre compte, créez un retour avec orderreturns.createorderreturn et définissez returnMethodType sur inStore.

Vous pouvez vérifier le montant remboursable de chaque article dans l'objet MerchantOrderReturn.

L'exemple suivant montre comment rembourser un client en espèces :

Voici un exemple d'URL : POST https://shoppingcontent.googleapis.com/content/v2.1/merchantId/orderreturns/returnId/process

Voici un exemple d'URL sandbox :

POST  https://shoppingcontent.googleapis.com/content/v2.1sandbox/merchantId/orderreturns/returnId/process

Voici un exemple de requête :

{
  "operationId": "process_op_1",
  "refundShippingFee": {
    "paymentType": "cash",
    "partialRefund": {
      "priceAmount": {
        "currency": "USD",
        "value": "5.99"
      },
      "taxAmount": {
        "currency": "USD",
        "value": "0"
      }
    },
    "reasonText": "canceled",
    "returnRefundReason": "customerCanceled"
  },
  "returnItems": [
    {
      "refund": {
        "paymentType": "cash",
        "partialRefund": {
          "priceAmount": {
            "currency": "USD",
            "value": "20"
          },
          "taxAmount": {
            "currency": "USD",
            "value": "0"
          }
        },
        "reasonText": "canceled",
        "returnRefundReason": "customerCanceled"
      },
      "returnItemId": "LCFJTDCD7NCZEYE"
    }
  ]
}

Tests

Étant donné que vous pouvez effectuer des tests en mode sandbox ou production, veillez à ne pas modifier les commandes en production par inadvertance.

Voici un exemple de workflow que vous pouvez suivre pour tester la ressource Orders :

Créez une commande test.

En production, une commande est créée automatiquement lorsqu'un client passe une commande. En mode sandbox, vous devez utiliser createtestorder ou l'UI Merchant Center pour créer une commande test.

Les commandes en production passent automatiquement de leur état de départ à pendingShipment. En mode sandbox, vous devez utiliser l'appel advancetestorder pour faire passer la commande à l'état "En attente d'expédition". Vous pouvez également utiliser le bouton APPROUVER dans l'onglet Commandes de Merchant Center pour effectuer cette étape.
Définissez la commande sur Shipped, puis sur Delivered via l'UI ou avec shiplineitems et updateshipment.
Créez un retour test.

En production, les clients déclenchent les retours. En mode sandbox, vous pouvez utiliser createtestreturn ou createorderreturn. Notez que vous pouvez obtenir les paramètres de requête requis lineItemId et quantity en effectuant l'appel orders.get pour une commande donnée.
Appelez les méthodes orderreturns.list, orderreturns.get, orderreturns.acknowledge et orderreturns.process pour effectuer des requêtes et traiter les retours.