Orders: custombatch

Requires authorization

Retrieves or modifies multiple orders in a single request. Try it now.

Note that we don't guarantee sequential placing of the actions within the batch. We highly recommend not issuing interdependent calls in a single batch request (like creating and updating the same shipment), as the result of this is undefined.

Request

HTTP request

POST https://www.googleapis.com/content/v2/orders/batch

Parameters

Parameter name Value Description

Authorization

This request requires authorization with the following scope (read more about authentication and authorization).

Scope
https://www.googleapis.com/auth/content

Request body

In the request body, supply data with the following structure:

{
  "entries": [
    {
      "batchId": unsigned integer,
      "merchantId": unsigned long,
      "orderId": string,
      "method": string,
      "operationId": string,
      "shipLineItems": {
        "lineItems": [
          {
            "lineItemId": string,
            "productId": string,
            "quantity": unsigned integer
          }
        ],
        "shipmentId": string,
        "carrier": string,
        "trackingId": string,
        "shipmentInfos": [
          {
            "shipmentId": string,
            "carrier": string,
            "trackingId": string
          }
        ]
      },
      "updateShipment": {
        "shipmentId": string,
        "status": string,
        "carrier": string,
        "trackingId": string
      },
      "cancel": {
        "reason": string,
        "reasonText": string
      },
      "cancelLineItem": {
        "lineItemId": string,
        "productId": string,
        "quantity": unsigned integer,
        "reason": string,
        "reasonText": string,
        "amount": {
          "value": string,
          "currency": string
        },
        "amountPretax": {
          "value": string,
          "currency": string
        },
        "amountTax": {
          "value": string,
          "currency": string
        }
      },
      "refund": {
        "amount": {
          "value": string,
          "currency": string
        },
        "amountPretax": {
          "value": string,
          "currency": string
        },
        "amountTax": {
          "value": string,
          "currency": string
        },
        "reason": string,
        "reasonText": string
      },
      "returnLineItem": {
        "lineItemId": string,
        "productId": string,
        "quantity": unsigned integer,
        "reason": string,
        "reasonText": string
      },
      "returnRefundLineItem": {
        "lineItemId": string,
        "productId": string,
        "quantity": unsigned integer,
        "reason": string,
        "reasonText": string,
        "amountPretax": {
          "value": string,
          "currency": string
        },
        "amountTax": {
          "value": string,
          "currency": string
        }
      },
      "rejectReturnLineItem": {
        "lineItemId": string,
        "productId": string,
        "quantity": unsigned integer,
        "reason": string,
        "reasonText": string
      },
      "inStoreRefundLineItem": {
        "lineItemId": string,
        "productId": string,
        "quantity": unsigned integer,
        "reason": string,
        "reasonText": string,
        "amountPretax": {
          "value": string,
          "currency": string
        },
        "amountTax": {
          "value": string,
          "currency": string
        }
      },
      "merchantOrderId": string,
      "setLineItemMetadata": {
        "lineItemId": string,
        "productId": string,
        "annotations": [
          {
            "key": string,
            "value": string
          }
        ]
      },
      "updateLineItemShippingDetails": {
        "lineItemId": string,
        "productId": string,
        "shipByDate": string,
        "deliverByDate": string
      }
    }
  ]
}
Property name Value Description Notes
entries[] list The request entries to be processed in the batch.
entries[].batchId unsigned integer An entry ID, unique within the batch request.
entries[].merchantId unsigned long The ID of the managing account.
entries[].orderId string The ID of the order. Required for all methods beside getByMerchantOrderId.
entries[].method string The method to apply.

Acceptable values are:
  • "acknowledge"
  • "cancel"
  • "cancelLineItem"
  • "get"
  • "getByMerchantOrderId"
  • "inStoreRefundLineItem"
  • "refund"
  • "rejectReturnLineItem"
  • "returnLineItem"
  • "returnRefundLineItem"
  • "setLineItemMetadata"
  • "shipLineItems"
  • "updateLineItemShippingDetails"
  • "updateMerchantOrderId"
  • "updateShipment"
entries[].operationId string The ID of the operation. Unique across all operations for a given order. Required for all methods beside get and getByMerchantOrderId.
entries[].shipLineItems nested object Required for shipLineItems method.
entries[].shipLineItems.shipmentId string Deprecated. Please use shipmentInfo instead. The ID of the shipment.
entries[].shipLineItems.lineItems[] list Line items to ship.
entries[].shipLineItems.lineItems[].lineItemId string The id of the line item that is shipped. Either lineItemId or productId is required.
entries[].shipLineItems.lineItems[].quantity unsigned integer The quantity that is shipped.
entries[].shipLineItems.carrier string Deprecated. Please use shipmentInfo instead. The carrier handling the shipment. See shipments[].carrier in the Orders resource representation for a list of acceptable values.
entries[].shipLineItems.trackingId string Deprecated. Please use shipmentInfo instead. The tracking id for the shipment.
entries[].updateShipment nested object Required for updateShipment method.
entries[].updateShipment.shipmentId string The ID of the shipment.
entries[].updateShipment.status string New status for the shipment. Not updated if missing.

Acceptable values are:
  • "delivered"
entries[].updateShipment.carrier string The carrier handling the shipment. Not updated if missing. See shipments[].carrier in the Orders resource representation for a list of acceptable values.
entries[].updateShipment.trackingId string The tracking id for the shipment. Not updated if missing.
entries[].cancel nested object Required for cancel method.
entries[].cancel.reason string The reason for the cancellation.

Acceptable values are:
  • "customerInitiatedCancel"
  • "malformedShippingAddress"
  • "noInventory"
  • "other"
  • "priceError"
  • "shippingPriceError"
  • "taxError"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
entries[].cancel.reasonText string The explanation of the reason.
entries[].cancelLineItem nested object Required for cancelLineItem method.
entries[].cancelLineItem.lineItemId string The ID of the line item to cancel. Either lineItemId or productId is required.
entries[].cancelLineItem.quantity unsigned integer The quantity to cancel.
entries[].cancelLineItem.reason string The reason for the cancellation.

Acceptable values are:
  • "customerInitiatedCancel"
  • "malformedShippingAddress"
  • "noInventory"
  • "other"
  • "priceError"
  • "shippingPriceError"
  • "taxError"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
entries[].cancelLineItem.reasonText string The explanation of the reason.
entries[].refund nested object Required for refund method.
entries[].refund.amount nested object The amount that is refunded.
entries[].refund.amount.value string The price represented as a number. writable
entries[].refund.amount.currency string The currency of the price. writable
entries[].refund.reason string The reason for the refund.

Acceptable values are:
  • "adjustment"
  • "courtesyAdjustment"
  • "customerCanceled"
  • "customerDiscretionaryReturn"
  • "deliveredLateByCarrier"
  • "feeAdjustment"
  • "lateShipmentCredit"
  • "noInventory"
  • "other"
  • "priceError"
  • "productArrivedDamaged"
  • "productNotAsDescribed"
  • "shippingCostAdjustment"
  • "taxAdjustment"
  • "undeliverableShippingAddress"
  • "wrongProductShipped"
entries[].refund.reasonText string The explanation of the reason.
entries[].returnLineItem nested object Required for returnLineItem method.
entries[].returnLineItem.lineItemId string The ID of the line item to return. Either lineItemId or productId is required.
entries[].returnLineItem.quantity unsigned integer The quantity to return.
entries[].returnLineItem.reason string The reason for the return.

Acceptable values are:
  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"
entries[].returnLineItem.reasonText string The explanation of the reason.
entries[].merchantOrderId string The merchant order id. Required for updateMerchantOrderId and getByMerchantOrderId methods.
entries[].cancelLineItem.amount nested object Amount to refund for the cancelation. Optional. If not set, Google will calculate the default based on the price and tax of the items involved. The amount must not be larger than the net amount left on the order.
entries[].cancelLineItem.amount.value string The price represented as a number. writable
entries[].cancelLineItem.amount.currency string The currency of the price. writable
entries[].shipLineItems.shipmentInfos[] list Shipment information. This field is repeated because a single line item can be shipped in several packages (and have several tracking IDs).
entries[].shipLineItems.shipmentInfos[].shipmentId string The ID of the shipment.
entries[].shipLineItems.shipmentInfos[].carrier string The carrier handling the shipment. See shipments[].carrier in the Orders resource representation for a list of acceptable values.
entries[].shipLineItems.shipmentInfos[].trackingId string The tracking id for the shipment.
entries[].shipLineItems.lineItems[].productId string The ID of the product to ship. This is the REST ID used in the products service. Either lineItemId or productId is required.
entries[].cancelLineItem.productId string The ID of the product to cancel. This is the REST ID used in the products service. Either lineItemId or productId is required.
entries[].returnLineItem.productId string The ID of the product to return. This is the REST ID used in the products service. Either lineItemId or productId is required.
entries[].cancelLineItem.amountPretax nested object Amount to refund for the cancelation. Optional. If not set, Google will calculate the default based on the price and tax of the items involved. The amount must not be larger than the net amount left on the order.
entries[].cancelLineItem.amountPretax.value string The price represented as a number. writable
entries[].cancelLineItem.amountPretax.currency string The currency of the price. writable
entries[].cancelLineItem.amountTax nested object Tax amount that correspond to cancellation amount in amountPretax.
entries[].cancelLineItem.amountTax.value string The price represented as a number. writable
entries[].cancelLineItem.amountTax.currency string The currency of the price. writable
entries[].refund.amountPretax nested object The amount that is refunded. Either amount or amountPretax and amountTax should be filled.
entries[].refund.amountPretax.value string The price represented as a number. writable
entries[].refund.amountPretax.currency string The currency of the price. writable
entries[].refund.amountTax nested object Tax amount that correspond to refund amount in amountPretax.
entries[].refund.amountTax.value string The price represented as a number. writable
entries[].refund.amountTax.currency string The currency of the price. writable
entries[].setLineItemMetadata nested object Required for setLineItemMetadata method.
entries[].setLineItemMetadata.lineItemId string The ID of the line item to set metadata. Either lineItemId or productId is required.
entries[].setLineItemMetadata.productId string The ID of the product to set metadata. This is the REST ID used in the products service. Either lineItemId or productId is required.
entries[].setLineItemMetadata.annotations[] list
entries[].setLineItemMetadata.annotations[].key string Key for additional merchant provided (as key-value pairs) annotation about the line item.
entries[].setLineItemMetadata.annotations[].value string Value for additional merchant provided (as key-value pairs) annotation about the line item.
entries[].updateLineItemShippingDetails nested object Required for updateLineItemShippingDate method.
entries[].updateLineItemShippingDetails.lineItemId string The ID of the line item to set metadata. Either lineItemId or productId is required.
entries[].updateLineItemShippingDetails.productId string The ID of the product to set metadata. This is the REST ID used in the products service. Either lineItemId or productId is required.
entries[].updateLineItemShippingDetails.shipByDate string Updated ship by date, in ISO 8601 format. If not specified only deliver by date is updated.
entries[].updateLineItemShippingDetails.deliverByDate string Updated delivery by date, in ISO 8601 format. If not specified only ship by date is updated.
entries[].returnRefundLineItem nested object Required for returnRefundLineItem method.
entries[].returnRefundLineItem.lineItemId string The ID of the line item to return. Either lineItemId or productId is required.
entries[].returnRefundLineItem.productId string The ID of the product to return. This is the REST ID used in the products service. Either lineItemId or productId is required.
entries[].returnRefundLineItem.quantity unsigned integer The quantity to return and refund.
entries[].returnRefundLineItem.reason string The reason for the return.

Acceptable values are:
  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"
entries[].returnRefundLineItem.reasonText string The explanation of the reason.
entries[].returnRefundLineItem.amountPretax nested object The amount that is refunded. Optional, but if filled then both amountPretax and amountTax must be set.
entries[].returnRefundLineItem.amountPretax.value string The price represented as a number. writable
entries[].returnRefundLineItem.amountPretax.currency string The currency of the price. writable
entries[].returnRefundLineItem.amountTax nested object Tax amount that correspond to refund amount in amountPretax.
entries[].returnRefundLineItem.amountTax.value string The price represented as a number. writable
entries[].returnRefundLineItem.amountTax.currency string The currency of the price. writable
entries[].rejectReturnLineItem nested object Required for rejectReturnLineItem method.
entries[].rejectReturnLineItem.lineItemId string The ID of the line item to return. Either lineItemId or productId is required.
entries[].rejectReturnLineItem.productId string The ID of the product to return. This is the REST ID used in the products service. Either lineItemId or productId is required.
entries[].rejectReturnLineItem.quantity unsigned integer The quantity to return and refund.
entries[].rejectReturnLineItem.reason string The reason for the return.

Acceptable values are:
  • "damagedOrUsed"
  • "missingComponent"
  • "notEligible"
  • "other"
  • "outOfReturnWindow"
entries[].rejectReturnLineItem.reasonText string The explanation of the reason.
entries[].inStoreRefundLineItem nested object Required for inStoreReturnLineItem method.
entries[].inStoreRefundLineItem.lineItemId string The ID of the line item to return. Either lineItemId or productId is required.
entries[].inStoreRefundLineItem.productId string The ID of the product to return. This is the REST ID used in the products service. Either lineItemId or productId is required.
entries[].inStoreRefundLineItem.quantity unsigned integer The quantity to return and refund.
entries[].inStoreRefundLineItem.reason string The reason for the return.

Acceptable values are:
  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"
entries[].inStoreRefundLineItem.reasonText string The explanation of the reason.
entries[].inStoreRefundLineItem.amountPretax nested object The amount that is refunded. Required.
entries[].inStoreRefundLineItem.amountPretax.value string The price represented as a number. writable
entries[].inStoreRefundLineItem.amountPretax.currency string The currency of the price. writable
entries[].inStoreRefundLineItem.amountTax nested object Tax amount that correspond to refund amount in amountPretax. Required.
entries[].inStoreRefundLineItem.amountTax.value string The price represented as a number. writable
entries[].inStoreRefundLineItem.amountTax.currency string The currency of the price. writable

Response

If successful, this method returns a response body with the following structure:

{
  "kind": "content#ordersCustomBatchResponse",
  "entries": [
    {
      "kind": "content#ordersCustomBatchResponseEntry",
      "batchId": unsigned integer,
      "order": orders Resource,
      "executionStatus": string,
      "errors": {
        "errors": [
          {
            "domain": string,
            "reason": string,
            "message": string
          }
        ],
        "code": unsigned integer,
        "message": string
      }
    }
  ]
}
Property name Value Description Notes
kind string Identifies what kind of resource this is. Value: the fixed string "content#ordersCustomBatchResponse".
entries[] list The result of the execution of the batch requests.
entries[].kind string Identifies what kind of resource this is. Value: the fixed string "content#ordersCustomBatchResponseEntry".
entries[].batchId unsigned integer The ID of the request entry this entry responds to.
entries[].order nested object The retrieved order. Only defined if the method is get and if the request was successful.
entries[].executionStatus string The status of the execution. Only defined if the method is not get or getByMerchantOrderId and if the request was successful.

Acceptable values are:
  • "duplicate"
  • "executed"
entries[].errors nested object A list of errors defined if and only if the request failed.
entries[].errors.errors[] list A list of errors.
entries[].errors.errors[].domain string The domain of the error.
entries[].errors.errors[].reason string The error code.
entries[].errors.errors[].message string A description of the error.
entries[].errors.code unsigned integer The HTTP status of the first error in errors.
entries[].errors.message string The message of the first error in errors.

Try it!

Use the APIs Explorer below to call this method on the Sandbox environment and see the response.
Alternatively, test this on live data.

Send feedback about...

Content API for Shopping