Method: orders.custombatch

Retrieves or modifies multiple orders in a single request.

HTTP request

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

Request body

The request body contains an instance of OrdersCustomBatchRequest.

Response body

If successful, the response body contains data with the following structure:

JSON representation
{
  "entries": [
    {
      object (OrdersCustomBatchResponseEntry)
    }
  ],
  "kind": string
}
Fields
entries[]

object (OrdersCustomBatchResponseEntry)

The result of the execution of the batch requests.

kind

string

Identifies what kind of resource this is. Value: the fixed string

"content#ordersCustomBatchResponse"

.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/content
  • https://www.googleapis.com/auth/structuredcontent

For more information, see the OAuth 2.0 Overview.

OrdersCustomBatchRequest

JSON representation
{
  "entries": [
    {
      object (OrdersCustomBatchRequestEntry)
    }
  ]
}
Fields
entries[]

object (OrdersCustomBatchRequestEntry)

The request entries to be processed in the batch.

OrdersCustomBatchRequestEntry

JSON representation
{
  "batchId": integer,
  "merchantId": string,
  "orderId": string,
  "method": string,
  "operationId": string,
  "shipLineItems": {
    object (OrdersCustomBatchRequestEntryShipLineItems)
  },
  "updateShipment": {
    object (OrdersCustomBatchRequestEntryUpdateShipment)
  },
  "cancel": {
    object (OrdersCustomBatchRequestEntryCancel)
  },
  "cancelLineItem": {
    object (OrdersCustomBatchRequestEntryCancelLineItem)
  },
  "refund": {
    object (OrdersCustomBatchRequestEntryRefund)
  },
  "returnLineItem": {
    object (OrdersCustomBatchRequestEntryReturnLineItem)
  },
  "merchantOrderId": string,
  "setLineItemMetadata": {
    object (OrdersCustomBatchRequestEntrySetLineItemMetadata)
  },
  "updateLineItemShippingDetails": {
    object (OrdersCustomBatchRequestEntryUpdateLineItemShippingDetails)
  },
  "returnRefundLineItem": {
    object (OrdersCustomBatchRequestEntryReturnRefundLineItem)
  },
  "inStoreRefundLineItem": {
    object (OrdersCustomBatchRequestEntryInStoreRefundLineItem)
  },
  "rejectReturnLineItem": {
    object (OrdersCustomBatchRequestEntryRejectReturnLineItem)
  }
}
Fields
batchId

integer (uint32 format)

An entry ID, unique within the batch request.

merchantId

string

The ID of the managing account.

orderId

string

The ID of the order. Required for all methods beside getByMerchantOrderId.

method

string

The method of the batch entry.

Acceptable values are:

  • "acknowledge"
  • "cancel"
  • "cancelLineItem"
  • "get"
  • "getByMerchantOrderId"
  • "inStoreRefundLineItem"
  • "refund"
  • "rejectReturnLineItem"
  • "returnLineItem"
  • "returnRefundLineItem"
  • "setLineItemMetadata"
  • "shipLineItems"
  • "updateLineItemShippingDetails"
  • "updateMerchantOrderId"
  • "updateShipment"

operationId

string

The ID of the operation. Unique across all operations for a given order. Required for all methods beside get and getByMerchantOrderId.

shipLineItems

object (OrdersCustomBatchRequestEntryShipLineItems)

Required for shipLineItems method.

updateShipment

object (OrdersCustomBatchRequestEntryUpdateShipment)

Required for updateShipment method.

cancel

object (OrdersCustomBatchRequestEntryCancel)

Required for cancel method.

cancelLineItem

object (OrdersCustomBatchRequestEntryCancelLineItem)

Required for cancelLineItem method.

refund

object (OrdersCustomBatchRequestEntryRefund)

Required for refund method.

returnLineItem

object (OrdersCustomBatchRequestEntryReturnLineItem)

Required for returnLineItem method.

merchantOrderId

string

The merchant order ID. Required for updateMerchantOrderId and getByMerchantOrderId methods.

setLineItemMetadata

object (OrdersCustomBatchRequestEntrySetLineItemMetadata)

Required for setLineItemMetadata method.

updateLineItemShippingDetails

object (OrdersCustomBatchRequestEntryUpdateLineItemShippingDetails)

Required for updateLineItemShippingDate method.

returnRefundLineItem

object (OrdersCustomBatchRequestEntryReturnRefundLineItem)

Required for returnRefundLineItem method.

inStoreRefundLineItem

object (OrdersCustomBatchRequestEntryInStoreRefundLineItem)

Required for inStoreReturnLineItem method.

rejectReturnLineItem

object (OrdersCustomBatchRequestEntryRejectReturnLineItem)

Required for rejectReturnLineItem method.

OrdersCustomBatchRequestEntryShipLineItems

JSON representation
{
  "shipmentId": string,
  "lineItems": [
    {
      object (OrderShipmentLineItemShipment)
    }
  ],
  "carrier": string,
  "trackingId": string,
  "shipmentInfos": [
    {
      object (OrdersCustomBatchRequestEntryShipLineItemsShipmentInfo)
    }
  ],
  "shipmentGroupId": string
}
Fields
shipmentId

string

Deprecated. Please use shipmentInfo instead. The ID of the shipment.

lineItems[]

object (OrderShipmentLineItemShipment)

Line items to ship.

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.

trackingId

string

Deprecated. Please use shipmentInfo instead. The tracking ID for the shipment.

shipmentInfos[]

object (OrdersCustomBatchRequestEntryShipLineItemsShipmentInfo)

Shipment information. This field is repeated because a single line item can be shipped in several packages (and have several tracking IDs).

shipmentGroupId

string

ID of the shipment group. Required for orders that use the orderinvoices service.

OrdersCustomBatchRequestEntryUpdateShipment

JSON representation
{
  "shipmentId": string,
  "status": string,
  "carrier": string,
  "trackingId": string,
  "deliveryDate": string
}
Fields
shipmentId

string

The ID of the shipment.

status

string

New status for the shipment. Not updated if missing.

Acceptable values are:

  • "delivered"
  • "undeliverable"
  • "readyForPickup"

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.

trackingId

string

The tracking ID for the shipment. Not updated if missing.

deliveryDate

string

Date on which the shipment has been delivered, in ISO 8601 format. Optional and can be provided only if status is delivered.

OrdersCustomBatchRequestEntryCancel

JSON representation
{
  "reason": string,
  "reasonText": string
}
Fields
reason

string

The reason for the cancellation.

Acceptable values are:

  • "customerInitiatedCancel"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "noInventory"
  • "other"
  • "priceError"
  • "shippingPriceError"
  • "taxError"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"

reasonText

string

The explanation of the reason.

OrdersCustomBatchRequestEntryCancelLineItem

JSON representation
{
  "lineItemId": string,
  "quantity": integer,
  "reason": string,
  "reasonText": string,
  "amount": {
    object (Price)
  },
  "productId": string,
  "amountPretax": {
    object (Price)
  },
  "amountTax": {
    object (Price)
  }
}
Fields
lineItemId

string

The ID of the line item to cancel. Either lineItemId or productId is required.

quantity

integer (uint32 format)

The quantity to cancel.

reason

string

The reason for the cancellation.

Acceptable values are:

  • "customerInitiatedCancel"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "noInventory"
  • "other"
  • "priceError"
  • "shippingPriceError"
  • "taxError"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"

reasonText

string

The explanation of the reason.

amount

object (Price)

Deprecated. Please use amountPretax and amountTax instead.

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.

amountPretax

object (Price)

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.

amountTax

object (Price)

Tax amount that corresponds to cancellation amount in amountPretax. Optional, but if filled, then amountPretax must be set. Calculated automatically if not provided.

OrdersCustomBatchRequestEntryRefund

JSON representation
{
  "amount": {
    object (Price)
  },
  "reason": string,
  "reasonText": string,
  "amountPretax": {
    object (Price)
  },
  "amountTax": {
    object (Price)
  }
}
Fields
amount

object (Price)

Deprecated. Please use amountPretax and amountTax instead.

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"

reasonText

string

The explanation of the reason.

amountPretax

object (Price)

The amount that is refunded. Either amount or amountPretax should be filled.

amountTax

object (Price)

Tax amount that corresponds to refund amount in amountPretax. Optional, but if filled, amountPretax must be set. Calculated automatically if not provided.

OrdersCustomBatchRequestEntryReturnLineItem

JSON representation
{
  "lineItemId": string,
  "quantity": integer,
  "reason": string,
  "reasonText": string,
  "productId": string
}
Fields
lineItemId

string

The ID of the line item to return. Either lineItemId or productId is required.

quantity

integer (uint32 format)

The quantity to return.

reason

string

The reason for the return.

Acceptable values are:

  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "deliveredTooLate"
  • "expiredItem"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "productNotAsDescribed"
  • "qualityNotAsExpected"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"

reasonText

string

The explanation of the reason.

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.

OrdersCustomBatchRequestEntrySetLineItemMetadata

JSON representation
{
  "lineItemId": string,
  "productId": string,
  "annotations": [
    {
      object (OrderMerchantProvidedAnnotation)
    }
  ]
}
Fields
lineItemId

string

The ID of the line item to set metadata. Either lineItemId or productId is required.

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.

annotations[]

object (OrderMerchantProvidedAnnotation)

OrdersCustomBatchRequestEntryUpdateLineItemShippingDetails

JSON representation
{
  "lineItemId": string,
  "productId": string,
  "shipByDate": string,
  "deliverByDate": string
}
Fields
lineItemId

string

The ID of the line item to set metadata. Either lineItemId or productId is required.

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.

shipByDate

string

Updated ship by date, in ISO 8601 format. If not specified only deliver by date is updated.

Provided date should be within 1 year timeframe and can not be a date in the past.

deliverByDate

string

Updated delivery by date, in ISO 8601 format. If not specified only ship by date is updated.

Provided date should be within 1 year timeframe and can not be a date in the past.

OrdersCustomBatchRequestEntryReturnRefundLineItem

JSON representation
{
  "lineItemId": string,
  "productId": string,
  "quantity": integer,
  "reason": string,
  "reasonText": string,
  "amountPretax": {
    object (Price)
  },
  "amountTax": {
    object (Price)
  }
}
Fields
lineItemId

string

The ID of the line item to return. Either lineItemId or productId is required.

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.

quantity

integer (uint32 format)

The quantity to return and refund.

reason

string

The reason for the return.

Acceptable values are:

  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "deliveredTooLate"
  • "expiredItem"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "productNotAsDescribed"
  • "qualityNotAsExpected"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"

reasonText

string

The explanation of the reason.

amountPretax

object (Price)

The amount that is refunded. If omitted, refundless return is assumed (same as calling returnLineItem method).

amountTax

object (Price)

Tax amount that corresponds to refund amount in amountPretax. Optional, but if filled, then amountPretax must be set. Calculated automatically if not provided.

OrdersCustomBatchRequestEntryInStoreRefundLineItem

JSON representation
{
  "lineItemId": string,
  "productId": string,
  "quantity": integer,
  "reason": string,
  "reasonText": string,
  "amountPretax": {
    object (Price)
  },
  "amountTax": {
    object (Price)
  }
}
Fields
lineItemId

string

The ID of the line item to return. Either lineItemId or productId is required.

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.

quantity

integer (uint32 format)

The quantity to return and refund.

reason

string

The reason for the return.

Acceptable values are:

  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "deliveredTooLate"
  • "expiredItem"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "productNotAsDescribed"
  • "qualityNotAsExpected"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"

reasonText

string

The explanation of the reason.

amountPretax

object (Price)

The amount that is refunded. Required.

amountTax

object (Price)

Tax amount that correspond to refund amount in amountPretax. Required.

OrdersCustomBatchRequestEntryRejectReturnLineItem

JSON representation
{
  "lineItemId": string,
  "productId": string,
  "quantity": integer,
  "reason": string,
  "reasonText": string
}
Fields
lineItemId

string

The ID of the line item to return. Either lineItemId or productId is required.

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.

quantity

integer (uint32 format)

The quantity to return and refund.

reason

string

The reason for the return.

Acceptable values are:

  • "damagedOrUsed"
  • "missingComponent"
  • "notEligible"
  • "other"
  • "outOfReturnWindow"

reasonText

string

The explanation of the reason.

OrdersCustomBatchResponseEntry

JSON representation
{
  "batchId": integer,
  "order": {
    object (Order)
  },
  "executionStatus": string,
  "errors": {
    object (Errors)
  },
  "kind": string
}
Fields
batchId

integer (uint32 format)

The ID of the request entry this entry responds to.

order

object (Order)

The retrieved order. Only defined if the method is get and if the request was successful.

executionStatus

string

The status of the execution. Only defined if

  1. the request was successful; and
  2. the method is not get, getByMerchantOrderId, or one of the test methods.


Acceptable values are:
  • "duplicate"
  • "executed"

errors

object (Errors)

A list of errors defined if and only if the request failed.

kind

string

Identifies what kind of resource this is. Value: the fixed string "content#ordersCustomBatchResponseEntry"