• Register

Add to Bag


This service enables users to add items to shopping bag for a user. It enables the user to add an item to the shopping bag with each request.

NOTE: If no user or bag is specified when adding an item, a guest bag/user is created. If you want to merge your guest bag with a specific user account, use Merge Bag.


back to top

HTTP Method and Request URL



back to top

HTTP, Path and Query Parameters

HTTP Header Parameters

Parameter Description Mandatory Sample Value
x-macys-webservice-client-id Pass the apikey as a header value which is called x-macys-webservice-client-id. The api key is the 24 character alphanumeric string assigned to your application when you registered it. Click here for a list of your API keys. Yes


Accept Specifies the output format. Can be application/json or application/xml. Yes



Content-Type Specifies the format of body sent. Can be application/json or application/xml. Yes



Cookie The cookie macys_online_uid needs to be set with the user id of the macys.com customer. Either this or UserID (guest id) param is required  macys_online_uid=user_id (macys.com)
Request Body Parameters
Parameter Description Mandatory Sample Value
upcId UPC ID that identifies the item  Yes, if UPC Number not entered 
pWPIndicator PWP (Purchase with a Purchase) indicator.  When adding a PWP to your bag this must be set to "true" No true
promotionid Promotion ID.  This must be present when adding a PWP to the bag
No 19825999
Quantity Quantity of the item selected  Yes  1
promocode Promotion code to be applied on the item/bag  No  
RegistryID If an item from the registry is selected, add registry ID  No  
WIshlistID If an item from a wishlist is selected, add registry ID  No  
customprice value of the gift card & only applicable for VGC/EGC  No  
syndicationitemid Only applicable for EGC  No  
recipientemail Recipients email for VGC  No  
from Name of user to be used in gift card subject  No  
message Gift card message  No  
to Recipients name  No  


back to top

Sample Requests and Responses

Sample Request

Request URL:



Sample Header:

X-Macys-Webservice-Client-Id: xmj9js4jkdpe1983fmwu98gh
Accept: application/json
Content-Type: application/json

Request Body(Payload)

    "item": {
        "quantity": "1",
        "upcId": "1628668"

Sample Response

    "bag": {
        "bagId": 138733692,
        "bagGUID": "11a2d0f7-d4a1-48eb-af1f-07fd17abb88b",
        "storeLocationNumber": 0,
        "owner": {
            "userId": 2194191065,
            "userGuid": "d4d8f7a7-3091-4dc7-b3d3-b36d14407c62",
            "bccUser": false,
            "userRegistryId": 0
        "shippingSummary": {
            "discount": 0,
            "method": "G",
            "standardCharges": 11,
            "standardChargesBeforeDicsount": 11,
            "surcharges": 0,
            "total": 11
        "bagSummary": {
            "estimatedTax": 6,
            "itemCount": 1,
            "grandTotal": 116.99,
            "merchandiseTotal": 99.99,
            "totalPersonalizationFee": 0,
            "totalSaved": 175.01,
            "yaqAmount": 0
        "promotions": [],
        "items": [
                "autoAddChoice": "ADD",
                "discount": 175.01,
                "giftCardAmount": 0,
                "giftId": 0,
                "personalizationFlag": false,
                "gwpItemFlag": false,
                "isItemFromWishList": false,
                "pwpItemFlag": false,
                "specialItemFlag": false,
                "itemTotal": 99.99,
                "mergeRequiredFlag": false,
                "originalPrice": 275,
                "personalizationFee": 0,
                "pickupRegistryApplicable": true,
                "pickUpFromStore": false,
                "promotionId": 0,
                "wishListId": 0,
                "quantity": 1,
                "retailPrice": 99.99,
                "sequenceNumber": 1,
                "siteAvailablilityFlag": true,
                "surcharges": 0,
                "productId": 1111748,
                "upcId": 1628668,
                "upcNumber": "886329769121",
                "uycTotalDiscountedPrice": 0,
                "uycDiscountedPercentage": 0,
                "uycPercentDiscount": 0
        "promotionOffers": [],
        "uycApplicable": false

back to top

Error Codes

Call Specific Error Codes:


General Error Handling Documentation:

Click Here

back to top

Docs Navigation