Skip to main content
POST
/
commerce
/
returns
/
{returnId}
/
payments
/
{paymentId}
/
actions
Error
A valid request URL is required to generate request examples
{
  "actionRequired": true,
  "attributes": [
    {
      "attributeDefinitionId": 123,
      "auditInfo": {
        "createBy": "<string>",
        "createDate": "2023-11-07T05:31:56Z",
        "updateBy": "<string>",
        "updateDate": "2023-11-07T05:31:56Z"
      },
      "fullyQualifiedName": "<string>",
      "values": [
        "<unknown>"
      ]
    }
  ],
  "auditInfo": {
    "createBy": "<string>",
    "createDate": "2023-11-07T05:31:56Z",
    "updateBy": "<string>",
    "updateDate": "2023-11-07T05:31:56Z"
  },
  "availableActions": [
    "<string>"
  ],
  "canInitiateRefund": true,
  "changeMessages": [
    {
      "amount": 123,
      "appId": "<string>",
      "appKey": "<string>",
      "appName": "<string>",
      "attributes": {},
      "correlationId": "<string>",
      "createDate": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "identifier": "<string>",
      "message": "<string>",
      "metadata": "<unknown>",
      "newValue": "<string>",
      "oldValue": "<string>",
      "subject": "<string>",
      "subjectType": "<string>",
      "success": true,
      "userFirstName": "<string>",
      "userId": "<string>",
      "userLastName": "<string>",
      "userScopeType": "<string>",
      "verb": "<string>"
    }
  ],
  "channelCode": "<string>",
  "contact": {
    "address": {
      "address1": "<string>",
      "address2": "<string>",
      "address3": "<string>",
      "address4": "<string>",
      "addressType": "<string>",
      "cityOrTown": "<string>",
      "countryCode": "<string>",
      "isValidated": true,
      "postalOrZipCode": "<string>",
      "stateOrProvince": "<string>"
    },
    "companyOrOrganization": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "id": 123,
    "lastNameOrSurname": "<string>",
    "middleNameOrInitial": "<string>",
    "phoneNumbers": {
      "home": "<string>",
      "mobile": "<string>",
      "work": "<string>"
    }
  },
  "currencyCode": "<string>",
  "customerAccountId": 123,
  "customerInteractionType": "<string>",
  "data": {},
  "externalId": "<string>",
  "id": "<string>",
  "isUnified": true,
  "items": [
    {
      "attributes": [
        {
          "attributeDefinitionId": 123,
          "auditInfo": {
            "createBy": "<string>",
            "createDate": "2023-11-07T05:31:56Z",
            "updateBy": "<string>",
            "updateDate": "2023-11-07T05:31:56Z"
          },
          "fullyQualifiedName": "<string>",
          "values": [
            "<unknown>"
          ]
        }
      ],
      "bundledProducts": [
        {
          "productCode": "<string>",
          "quantity": 123
        }
      ],
      "data": {},
      "dispositionInfo": [
        {
          "condition": "<string>",
          "locationCode": "<string>",
          "quantity": 123,
          "status": "<string>"
        }
      ],
      "excludeProductExtras": true,
      "id": "<string>",
      "inventoryTags": [
        {
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "notes": [
        {
          "auditInfo": {
            "createBy": "<string>",
            "createDate": "2023-11-07T05:31:56Z",
            "updateBy": "<string>",
            "updateDate": "2023-11-07T05:31:56Z"
          },
          "id": "<string>",
          "text": "<string>"
        }
      ],
      "orderItemId": "<string>",
      "orderItemOptionAttributeFQN": "<string>",
      "orderLineId": 123,
      "product": {
        "allocationExpiration": "2023-11-07T05:31:56Z",
        "allocationId": 123,
        "description": "<string>",
        "fulfillmentStatus": "<string>",
        "goodsType": "<string>",
        "isPackagedStandAlone": true,
        "measurements": {
          "height": {
            "unit": "<string>",
            "value": 123
          },
          "length": {
            "unit": "<string>",
            "value": 123
          },
          "weight": {
            "unit": "<string>",
            "value": 123
          },
          "width": {
            "unit": "<string>",
            "value": 123
          }
        },
        "name": "<string>",
        "productCode": "<string>",
        "productReservationId": 123,
        "stock": {
          "aggregateInventory": 123,
          "availableDate": "2023-11-07T05:31:56Z",
          "availableFutureInventories": 123,
          "futureInventories": [
            {
              "allocated": 123,
              "available": 123,
              "createDate": "2023-11-07T05:31:56Z",
              "deliveryDate": "2023-11-07T05:31:56Z",
              "futureInventoryID": 123,
              "onhand": 123,
              "pending": 123
            }
          ],
          "isOnBackOrder": true,
          "isSubstitutable": true,
          "manageStock": true,
          "stockAvailable": 123,
          "totalAvailableStock": 123
        },
        "bundledProducts": [
          {
            "allocationExpiration": "2023-11-07T05:31:56Z",
            "allocationId": 123,
            "description": "<string>",
            "fulfillmentStatus": "<string>",
            "goodsType": "<string>",
            "isPackagedStandAlone": true,
            "measurements": {
              "height": {
                "unit": "<string>",
                "value": 123
              },
              "length": {
                "unit": "<string>",
                "value": 123
              },
              "weight": {
                "unit": "<string>",
                "value": 123
              },
              "width": {
                "unit": "<string>",
                "value": 123
              }
            },
            "name": "<string>",
            "productCode": "<string>",
            "productReservationId": 123,
            "stock": {
              "aggregateInventory": 123,
              "availableDate": "2023-11-07T05:31:56Z",
              "availableFutureInventories": 123,
              "futureInventories": [
                {
                  "allocated": 123,
                  "available": 123,
                  "createDate": "2023-11-07T05:31:56Z",
                  "deliveryDate": "2023-11-07T05:31:56Z",
                  "futureInventoryID": 123,
                  "onhand": 123,
                  "pending": 123
                }
              ],
              "isOnBackOrder": true,
              "isSubstitutable": true,
              "manageStock": true,
              "stockAvailable": 123,
              "totalAvailableStock": 123
            },
            "creditValue": 123,
            "deltaPrice": 123,
            "imageUrl": "<string>",
            "optionAttributeFQN": "<string>",
            "optionValue": "<unknown>",
            "quantity": 123
          }
        ],
        "categories": [
          {
            "id": 123,
            "parent": {}
          }
        ],
        "condition": "<string>",
        "discountsRestricted": true,
        "discountsRestrictedEndDate": "2023-11-07T05:31:56Z",
        "discountsRestrictedStartDate": "2023-11-07T05:31:56Z",
        "fulfillmentFields": [
          {
            "name": "<string>",
            "required": true,
            "userEnteredValue": null
          }
        ],
        "fulfillmentTypesSupported": [
          "<string>"
        ],
        "imageAlternateText": "<string>",
        "imageUrl": "<string>",
        "isRecurring": true,
        "isTaxable": true,
        "mfgPartNumber": "<string>",
        "options": [
          {
            "attributeFQN": "<string>",
            "dataType": "<string>",
            "name": "<string>",
            "shopperEnteredValue": "<unknown>",
            "stringValue": "<string>",
            "value": "<unknown>"
          }
        ],
        "price": {
          "creditValue": 123,
          "isOverRidePriceSalePrice": true,
          "msrp": 123,
          "price": 123,
          "priceListCode": "<string>",
          "priceListEntryMode": "<string>",
          "salePrice": 123,
          "tenantOverridePrice": 123
        },
        "productType": "<string>",
        "productUsage": "<string>",
        "properties": [
          {
            "attributeFQN": "<string>",
            "dataType": "<string>",
            "isMultiValue": true,
            "name": "<string>",
            "values": [
              {
                "stringValue": "<string>",
                "value": null
              }
            ]
          }
        ],
        "serialNumber": "<string>",
        "sku": "<string>",
        "upc": "<string>",
        "variationProductCode": "<string>"
      },
      "productLossAmount": 123,
      "productLossTaxAmount": 123,
      "quantityReceived": 123,
      "quantityRefunded": 123,
      "quantityReplaced": 123,
      "quantityRestockable": 123,
      "quantityRestocked": 123,
      "quantityShipped": 123,
      "reasons": [
        {
          "quantity": 123,
          "reason": "<string>"
        }
      ],
      "receiveStatus": "<string>",
      "refundAmount": 123,
      "refundStatus": "<string>",
      "replaceStatus": "<string>",
      "returnNotRequired": true,
      "returnProcessingFeeApplied": 123,
      "returnType": "<string>",
      "shipmentItemId": 123,
      "shipmentNumber": 123,
      "shippingAndHandlingRefunded": true,
      "shippingLossAmount": 123,
      "shippingLossTaxAmount": 123,
      "taxData": {},
      "totalWithWeightedShippingAndHandling": 123,
      "totalWithoutWeightedShippingAndHandling": 123
    }
  ],
  "locationCode": "<string>",
  "lossTotal": 123,
  "notes": [
    {
      "auditInfo": {
        "createBy": "<string>",
        "createDate": "2023-11-07T05:31:56Z",
        "updateBy": "<string>",
        "updateDate": "2023-11-07T05:31:56Z"
      },
      "id": "<string>",
      "text": "<string>"
    }
  ],
  "originalOrderId": "<string>",
  "originalOrderNumber": 123,
  "overrideReturnRule": true,
  "packages": [
    {
      "auditInfo": {
        "createBy": "<string>",
        "createDate": "2023-11-07T05:31:56Z",
        "updateBy": "<string>",
        "updateDate": "2023-11-07T05:31:56Z"
      },
      "availableActions": [
        "<string>"
      ],
      "changeMessages": [
        {
          "amount": 123,
          "appId": "<string>",
          "appKey": "<string>",
          "appName": "<string>",
          "attributes": {},
          "correlationId": "<string>",
          "createDate": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "identifier": "<string>",
          "message": "<string>",
          "metadata": "<unknown>",
          "newValue": "<string>",
          "oldValue": "<string>",
          "subject": "<string>",
          "subjectType": "<string>",
          "success": true,
          "userFirstName": "<string>",
          "userId": "<string>",
          "userLastName": "<string>",
          "userScopeType": "<string>",
          "verb": "<string>"
        }
      ],
      "code": "<string>",
      "fulfillmentDate": "2023-11-07T05:31:56Z",
      "fulfillmentLocationCode": "<string>",
      "id": "<string>",
      "items": [
        {
          "fulfillmentItemType": "<string>",
          "lineId": 123,
          "optionAttributeFQN": "<string>",
          "productCode": "<string>",
          "quantity": 123
        }
      ],
      "status": "<string>",
      "attributes": {},
      "carrier": "<string>",
      "fxcbDocumentsUrl": "<string>",
      "fxcbPackNotificationId": "<string>",
      "hasLabel": true,
      "integratorId": "<string>",
      "labelFormat": "<string>",
      "manifestId": "<string>",
      "measurements": {
        "height": {
          "unit": "<string>",
          "value": 123
        },
        "length": {
          "unit": "<string>",
          "value": 123
        },
        "weight": {
          "unit": "<string>",
          "value": 123
        },
        "width": {
          "unit": "<string>",
          "value": 123
        }
      },
      "packageId": "<string>",
      "packagingType": "<string>",
      "packingSlipItemDetails": [
        {
          "attributes": {},
          "lineId": 123,
          "originalOrderItemId": "<string>",
          "quantity": 123
        }
      ],
      "packingSlipNumber": 123,
      "returnCarrier": "<string>",
      "returnTrackingNumbers": [
        "<string>"
      ],
      "returnTrackings": [
        {
          "attributes": {},
          "number": "<string>",
          "url": "<string>"
        }
      ],
      "shipmentId": "<string>",
      "shippingMethodCode": "<string>",
      "shippingMethodName": "<string>",
      "signatureRequired": true,
      "trackingNumber": "<string>",
      "trackingNumbers": [
        "<string>"
      ],
      "trackings": [
        {
          "attributes": {},
          "number": "<string>",
          "url": "<string>"
        }
      ]
    }
  ],
  "payments": [
    {
      "amountCollected": 123,
      "amountCredited": 123,
      "amountRequested": 123,
      "auditInfo": {
        "createBy": "<string>",
        "createDate": "2023-11-07T05:31:56Z",
        "updateBy": "<string>",
        "updateDate": "2023-11-07T05:31:56Z"
      },
      "availableActions": [
        "<string>"
      ],
      "billingInfo": {
        "auditInfo": {
          "createBy": "<string>",
          "createDate": "2023-11-07T05:31:56Z",
          "updateBy": "<string>",
          "updateDate": "2023-11-07T05:31:56Z"
        },
        "billingContact": {
          "address": {
            "address1": "<string>",
            "address2": "<string>",
            "address3": "<string>",
            "address4": "<string>",
            "addressType": "<string>",
            "cityOrTown": "<string>",
            "countryCode": "<string>",
            "isValidated": true,
            "postalOrZipCode": "<string>",
            "stateOrProvince": "<string>"
          },
          "companyOrOrganization": "<string>",
          "email": "<string>",
          "firstName": "<string>",
          "id": 123,
          "lastNameOrSurname": "<string>",
          "middleNameOrInitial": "<string>",
          "phoneNumbers": {
            "home": "<string>",
            "mobile": "<string>",
            "work": "<string>"
          }
        },
        "card": {
          "bin": "<string>",
          "cardNumberPartOrMask": "<string>",
          "expireMonth": 123,
          "expireYear": 123,
          "paymentOrCardType": "<string>",
          "ccLastFour": "<string>",
          "isCardInfoSaved": true,
          "isTokenized": true,
          "isUsedRecurring": true,
          "nameOnCard": "<string>",
          "paymentServiceCardId": "<string>"
        },
        "check": {
          "checkNumber": "<string>"
        },
        "customCreditType": "<string>",
        "data": {},
        "externalTransactionId": "<string>",
        "isRecurring": true,
        "isSameBillingShippingAddress": true,
        "paymentType": "<string>",
        "paymentWorkflow": "<string>",
        "purchaseOrder": {
          "customFields": [
            {
              "code": "<string>",
              "label": "<string>",
              "value": "<string>"
            }
          ],
          "paymentTerm": {
            "code": "<string>",
            "description": "<string>"
          },
          "purchaseOrderNumber": "<string>"
        },
        "recurringTransactionId": "<string>",
        "storeCreditCode": "<string>",
        "storeCreditType": "<string>",
        "token": {
          "paymentServiceTokenId": "<string>",
          "type": "<string>"
        }
      },
      "changeMessages": [
        {
          "amount": 123,
          "appId": "<string>",
          "appKey": "<string>",
          "appName": "<string>",
          "attributes": {},
          "correlationId": "<string>",
          "createDate": "2023-11-07T05:31:56Z",
          "id": "<string>",
          "identifier": "<string>",
          "message": "<string>",
          "metadata": "<unknown>",
          "newValue": "<string>",
          "oldValue": "<string>",
          "subject": "<string>",
          "subjectType": "<string>",
          "success": true,
          "userFirstName": "<string>",
          "userId": "<string>",
          "userLastName": "<string>",
          "userScopeType": "<string>",
          "verb": "<string>"
        }
      ],
      "data": {},
      "externalTransactionId": "<string>",
      "gatewayGiftCard": {
        "amount": 123,
        "cardNumber": "<string>",
        "cardPin": "<string>",
        "currencyCode": "<string>",
        "id": "<string>"
      },
      "groupId": {
        "targetId": "<string>",
        "targetNumber": 123,
        "targetType": "<string>"
      },
      "id": "<string>",
      "installmentPlanCode": "<string>",
      "interactions": [
        {
          "amount": 123,
          "auditInfo": {
            "createBy": "<string>",
            "createDate": "2023-11-07T05:31:56Z",
            "updateBy": "<string>",
            "updateDate": "2023-11-07T05:31:56Z"
          },
          "capturableShipmentsSummary": [
            {
              "amountApplied": 123,
              "shipmentNumber": 123,
              "shipmentTotal": 123
            }
          ],
          "checkNumber": "<string>",
          "currencyCode": "<string>",
          "gatewayAVSCodes": "<string>",
          "gatewayAuthCode": "<string>",
          "gatewayCVV2Codes": "<string>",
          "gatewayInteractionId": 123,
          "gatewayResponseCode": "<string>",
          "gatewayResponseData": [
            {
              "key": "<string>",
              "value": "<string>"
            }
          ],
          "gatewayResponseText": "<string>",
          "gatewayTransactionId": "<string>",
          "id": "<string>",
          "interactionDate": "2023-11-07T05:31:56Z",
          "interactionType": "<string>",
          "isManual": true,
          "isPending": true,
          "isRecurring": true,
          "note": "<string>",
          "orderId": "<string>",
          "paymentEntryStatus": "<string>",
          "paymentId": "<string>",
          "paymentTransactionInteractionIdReference": 123,
          "refundId": "<string>",
          "returnId": "<string>",
          "status": "<string>",
          "target": {
            "targetId": "<string>",
            "targetNumber": 123,
            "targetType": "<string>"
          }
        }
      ],
      "isRecurring": true,
      "orderId": "<string>",
      "paymentServiceTransactionId": "<string>",
      "paymentType": "<string>",
      "paymentWorkflow": "<string>",
      "status": "<string>",
      "subPayments": [
        {
          "amountCollected": 123,
          "amountCredited": 123,
          "amountRefunded": 123,
          "amountRequested": 123,
          "status": "<string>",
          "target": {
            "targetId": "<string>",
            "targetNumber": 123,
            "targetType": "<string>"
          }
        }
      ]
    }
  ],
  "pickupDate": "2023-11-07T05:31:56Z",
  "productLossTaxTotal": 123,
  "productLossTotal": 123,
  "receiveStatus": "<string>",
  "refundAmount": 123,
  "refundStatus": "<string>",
  "refundToGC": true,
  "replaceStatus": "<string>",
  "returnNumber": 123,
  "returnOrderId": "<string>",
  "returnType": "<string>",
  "rmaDeadline": "2023-11-07T05:31:56Z",
  "shipOrBillCountryCode": "<string>",
  "shippingLossTaxTotal": 123,
  "shippingLossTotal": 123,
  "siteId": 123,
  "status": "<string>",
  "taxData": {},
  "tenantId": 123,
  "userId": "<string>",
  "visitId": "<string>",
  "webSessionId": "<string>"
}

Authorizations

​
Authorization
string
header
required

JWT Authorization header using the Bearer scheme.

Path Parameters

​
returnId
string
required
​
paymentId
string
required

Query Parameters

​
responseFields
string

limits which fields are returned in the response body

Body

application/json

Action to specify. Possible actions can be "Create," "Capture," "Void," "AuthCapture," or "ReceiveCheck."

​
actionName
string | null

Name of the Action to post

​
amount
number<double> | null

Amount of funds to withdraw to pay for this order.

​
cancelUrl
string | null

If paying by Paypal Express or some other potential non-gateway payment provider, a cancel redirect URL must be provided. This will be used if something goes wrong on the third-party side.

​
checkNumber
string | null

If paying by check, the check number.

​
currencyCode
string | null

ISO currency code for the transaction. Currently, only USD is supported.

​
data
object

Custom data from payment providers

​
externalTransactionId
string | null
​
installmentPlanCode
string | null

Stores the Installment Plan code. Installment is only supported on subscription orders

​
interactionDate
string<date-time> | null

Date the interaction occurred

​
manualGatewayInteraction
object

Represents a manually entered payment gateway interaction.

​
newBillingInfo
object

Customer's payment details such as payment type (credit card, check by mail, or PayPal) and cardholder information if payment is by credit card.

​
recaptcha
string | null

Recaptcha for validation.

​
referenceSourcePaymentId
string | null

Reference payment id from which to copy the billing info.

​
returnUrl
string | null

If paying by Paypal Express or some other potential non-gateway payment provider, a return redirect URL must be provided.

Response

Success

​
actionRequired
boolean

To find Returns that have failed to refund.

​
attributes
object[] | null

Collection of custom attributes associated with the return.

​
auditInfo
object
​
availableActions
string[] | null

Current available actions.

​
canInitiateRefund
boolean

To identify Return is refundable or not.

​
changeMessages
object[] | null

Change messages related to the return.

​
channelCode
string | null

Unique identifier of the channel for this item.

​
contact
object
​
currencyCode
string | null

ISO Currency Code. Currently, only USD is supported.

​
customerAccountId
integer<int32> | null

Unique identifier of the customer account.

​
customerInteractionType
string | null

Determines the interaction type that a customer will use to create this object. Valid values are: Website, Store, Call, Unknown

​
data
object

Custom data for a given vendor set within the commerce process.

​
externalId
string | null

A return can be created from an external system. This field is used to store the external id.

​
id
string | null

Unique Identifier for this Return

​
isUnified
boolean

Was this return created by the Unified platform.

​
items
object[] | null

The list of items being returned by the Shopper and replaced by the Merchant in this Return.

​
locationCode
string | null

Location code where the return was made/processed

​
lossTotal
number<double> | null

Sum of the ProductLossTotal and the ShippingLossTotal.

​
notes
object[] | null

Any Merchant Notes for this Return.

​
originalOrderId
string | null

The Id of the Order that this Return was generated from.

​
originalOrderNumber
integer<int32> | null

The order number that this return was generated from.

​
overrideReturnRule
boolean

When this is set to true, the return rules will be ignored, and a return will be created without any checks.

​
packages
object[] | null

Shipping package associated with this return.

​
payments
object[] | null

Any Refund payments associated with this Return.

​
pickupDate
string<date-time> | null

Pickupdate is the date when the return was picked up by the carrier. This is optional.

​
productLossTaxTotal
number<double> | null

The Total Taxes assessed on the product loss.

​
productLossTotal
number<double> | null

The Total Loss Amount is equal to the (cost of item) * quantity of item returned. It is meant to represent the product value to the merchant of the items damaged or returned by a shopper.

​
receiveStatus
string | null

A rollup status describing whether the return items have been received. See Mozu.CommerceRuntime.Contracts.Returns.Return.ReceiveStatusConst for possible values.

​
refundAmount
number<double> | null

If this Return was refunded, how much was credited to the shopper? This amount is summed from the refund payments.

​
refundStatus
string | null

A rollup status describing whether the return items have been refunded. See Mozu.CommerceRuntime.Contracts.Returns.Return.RefundStatusConst for possible values.

​
refundToGC
boolean

If this Flag is true, Refund will be done on new Gift Card.

​
replaceStatus
string | null

A rollup status describing whether the return items have been marked as replaced. See Mozu.CommerceRuntime.Contracts.Returns.Return.ReplaceStatusConst for possible values.

​
returnNumber
integer<int32> | null

A human-facing identifier that is unique within a tenant to represent the sequential ordering of Returns.

​
returnOrderId
string | null

The Id of the Order that represents the items shipped to the shopper for this Return.

​
returnType
string | null

Specifies whether this Return was a Refund or a Replace

​
rmaDeadline
string<date-time> | null

The deadline for a Shopper to ship the items in this Return to the Merchant.

​
shipOrBillCountryCode
string | null

ShipOrBillCountryCode contains country code of shipping address or Billing address

​
shippingLossTaxTotal
number<double> | null

The Total Taxes assessed on the shipping loss.

​
shippingLossTotal
number<double> | null

The Shipping Loss Total is equal to the (shipping cost of item) * quantity of item returned. It is meant to represent the product value to the merchant of the items damaged or returned by a shopper.

​
siteId
integer<int32> | null

Unique identifier of the Site.

​
status
string | null

The Status of the Return. Valid values are Null, Created, ReturnAuthorized, ReturnPending, ReturnReceived, ReplacementShipped, Cancelled, and Closed.

​
taxData
object

Storage for any additional/custom tax data.

​
tenantId
integer<int32> | null

Unique identifier of the Tenant.

​
userId
string | null

Unique identifier of the current user.

​
visitId
string | null

Identifies the Visit ID that was current when the order was placed or when the cart was last updated.

​
webSessionId
string | null

Identifies the web session used to place the order or last update the cart.