Orders: custombatch

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,
        "shipmentGroupId": string,
        "shipmentInfos": [
          {
            "shipmentId": string,
            "carrier": string,
            "trackingId": string
          }
        ]
      },
      "updateShipment": {
        "shipmentId": string,
        "status": string,
        "carrier": string,
        "trackingId": string,
        "deliveryDate": 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`" "`undeliverable`"
`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
`entries[].shipLineItems.shipmentGroupId`	`string`	ID of the shipment group. Required for orders that use the orderinvoices service.
`entries[].updateShipment.deliveryDate`	`string`	Date on which the shipment has been delivered, in ISO 8601 format. Optional and can be provided only if `status` is `delivered`.

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
`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.