Promotion and Coupon Services V3

Description
Request URL
Path and Query Parameters
Sample Requests and Responses
Error Codes

Description

The Promotion and Coupon API call allows users to retrieve promotions, coupons, or both using one call.

HTTP Method and Request URL

GET

https://api.macys.com/v3/promotions?show=coupons,promotions&promoid=[promoid]&global=[Y/N]&promotionsourcecode=[B/Z/D]&promotype=[type]&promocode=[promo_code]&channel=[channel]&coupontype=[coupontype]&couponnumber=[couponnumber]

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	xmj9js4jkdpe1983fmwu98gh
Accept	Detemines output format. Can be application/json or application/xml.	Yes	application/json application/xml

Query Parameters

Parameter	Description	Mandatory	Sample Value
show	Filter criteria for promotions and Coupons	Yes	promotions,coupons
promoid	Promotion Id	No	431690
global	Is the promotion global? (Y for Yes, N for No)	No	Y, N
promotionSourceCode	Promotion Source Code	No	B, Z, D
promotype	Promotion Type	No	20PercentOffOrder
promocode	Promotion Code	No	VETDAY
promotionfilterattribute	Promotion filter (Parameter is dynamic. see example)
channel	Channel for Promotion or Coupon	No	MOBILE
coupontype	Coupon Type	No	Email Marketing Other
couponfilterattribute	Coupon filter (Parameter is dynamic. see example)	No	IS_OFFERS_ELIGIBLE=N CPN_TYPE=COUPON CPN_ASSOCIATED_FOB_ID=1000
couponnumber	Coupon filter number	No	63
callback	If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned.	No	magicofmacysapi

Sample Requests and Responses

Sample Request

Request URL:

GET

https://api.macys.com/v3/promotions?show=coupons&global=Y&coupontype=Other

HTTP Header:

x-macys-webservice-client-id: xmj9js4jkdpe1983fmwu98gh

Accept: application/json

Sample Response

 {  
    "promotions"  :     [{  
      "coupon"  :     {  
        "couponId"  :     63  ,  
        "couponUrl"  :     "http://www1.macys.com/cms/deals/CAMPUS_AMBASSADOR_15percent_off_W3060163"  ,  
        "couponHeading"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  ,  
        "couponDescription"  :     "Outdoor_Pass"  ,  
        "couponShortCode"  :     "CAMPUS "  ,  
        "couponNumber"  :     "00030492100318133415 "  ,  
        "couponType"  :     "Other"  ,  
        "couponEffectiveDay"  :     1  ,  
        "couponEffectiveMonth"  :     8  ,  
        "couponEffectiveYear"  :     2013  ,  
        "couponExpirationDay"  :     31  ,  
        "couponExpirationMonth"  :     10  ,  
        "couponExpirationYear"  :     2013  ,  
        "displayStartDate"  :     "2013-08-01T00:00:00-04:00"  ,  
        "displayEndDate"  :     "2013-10-31T00:00:00-04:00"  ,  
        "couponAttributes"  :     [{  
          "attributeName"  :     "CPN_ASSOCIATED_FOB_ID"  ,  
          "attributeValue"  :     "1000"  
        },     {  
          "attributeName"  :     "CPN_SEO_DESCRIPTION"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_KEYWORDS"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_TITLE"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "IS_OFFERS_ELIGIBLE"  ,  
          "attributeValue"  :     "N"  
        }]  
      }  
    },     {  
      "coupon"  :     {  
        "couponId"  :     201  ,  
        "couponUrl"  :     "http://www1.macys.com/cms/deals/CAMPUS_AMBASSADOR_15percent_off_W3060163_CAMPUS15"  ,  
        "couponHeading"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  ,  
        "couponDescription"  :     "Outdoor_Pass"  ,  
        "couponShortCode"  :     "CAMPUS15 "  ,  
        "couponNumber"  :     "00030492100318133415 "  ,  
        "couponType"  :     "Other"  ,  
        "couponEffectiveDay"  :     1  ,  
        "couponEffectiveMonth"  :     8  ,  
        "couponEffectiveYear"  :     2013  ,  
        "couponExpirationDay"  :     31  ,  
        "couponExpirationMonth"  :     10  ,  
        "couponExpirationYear"  :     2013  ,  
        "displayStartDate"  :     "2013-08-01T00:00:00-04:00"  ,  
        "displayEndDate"  :     "2013-10-31T00:00:00-04:00"  ,  
        "couponAttributes"  :     [{  
          "attributeName"  :     "CPN_ASSOCIATED_FOB_ID"  ,  
          "attributeValue"  :     "1000"  
        },     {  
          "attributeName"  :     "CPN_SEO_DESCRIPTION"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_KEYWORDS"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_TITLE"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "IS_OFFERS_ELIGIBLE"  ,  
          "attributeValue"  :     "N"  
        }]  
      }  
    },     {  
      "coupon"  :     {  
        "couponId"  :     202  ,  
        "couponUrl"  :     "http://www1.macys.com/cms/deals/CAMPUS_AMBASSADOR_15percent_off_W3060163_BOOKS"  ,  
        "couponHeading"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  ,  
        "couponDescription"  :     "Outdoor_Pass"  ,  
        "couponShortCode"  :     "BOOKS "  ,  
        "couponNumber"  :     "00030492100318133415 "  ,  
        "couponType"  :     "Other"  ,  
        "couponEffectiveDay"  :     1  ,  
        "couponEffectiveMonth"  :     8  ,  
        "couponEffectiveYear"  :     2013  ,  
        "couponExpirationDay"  :     31  ,  
        "couponExpirationMonth"  :     10  ,  
        "couponExpirationYear"  :     2013  ,  
        "displayStartDate"  :     "2013-08-01T00:00:00-04:00"  ,  
        "displayEndDate"  :     "2013-10-31T00:00:00-04:00"  ,  
        "couponAttributes"  :     [{  
          "attributeName"  :     "CPN_ASSOCIATED_FOB_ID"  ,  
          "attributeValue"  :     "1000"  
        },     {  
          "attributeName"  :     "CPN_SEO_DESCRIPTION"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_KEYWORDS"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_TITLE"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "IS_OFFERS_ELIGIBLE"  ,  
          "attributeValue"  :     "N"  
        }]  
      }  
    },     {  
      "coupon"  :     {  
        "couponId"  :     203  ,  
        "couponUrl"  :     "http://www1.macys.com/cms/deals/CAMPUS_AMBASSADOR_15percent_off_W3060163_BOOKS15"  ,  
        "couponHeading"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  ,  
        "couponDescription"  :     "Outdoor_Pass"  ,  
        "couponShortCode"  :     "BOOKS15 "  ,  
        "couponNumber"  :     "00030492100318133415 "  ,  
        "couponType"  :     "Other"  ,  
        "couponEffectiveDay"  :     1  ,  
        "couponEffectiveMonth"  :     8  ,  
        "couponEffectiveYear"  :     2013  ,  
        "couponExpirationDay"  :     31  ,  
        "couponExpirationMonth"  :     10  ,  
        "couponExpirationYear"  :     2013  ,  
        "displayStartDate"  :     "2013-08-01T00:00:00-04:00"  ,  
        "displayEndDate"  :     "2013-10-31T00:00:00-04:00"  ,  
        "couponAttributes"  :     [{  
          "attributeName"  :     "CPN_ASSOCIATED_FOB_ID"  ,  
          "attributeValue"  :     "1000"  
        },     {  
          "attributeName"  :     "CPN_SEO_DESCRIPTION"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_KEYWORDS"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_TITLE"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "IS_OFFERS_ELIGIBLE"  ,  
          "attributeValue"  :     "N"  
        }]  
      }  
    },     {  
      "coupon"  :     {  
        "couponId"  :     204  ,  
        "couponUrl"  :     "http://www1.macys.com/cms/deals/CAMPUS_AMBASSADOR_15percent_off_W3060163_COLLEGE"  ,  
        "couponHeading"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  ,  
        "couponDescription"  :     "Outdoor_Pass"  ,  
        "couponShortCode"  :     "COLLEGE "  ,  
        "couponNumber"  :     "00030492100318133415 "  ,  
        "couponType"  :     "Other"  ,  
        "couponEffectiveDay"  :     1  ,  
        "couponEffectiveMonth"  :     8  ,  
        "couponEffectiveYear"  :     2013  ,  
        "couponExpirationDay"  :     31  ,  
        "couponExpirationMonth"  :     10  ,  
        "couponExpirationYear"  :     2013  ,  
        "displayStartDate"  :     "2013-08-01T00:00:00-04:00"  ,  
        "displayEndDate"  :     "2013-10-31T00:00:00-04:00"  ,  
        "couponAttributes"  :     [{  
          "attributeName"  :     "CPN_ASSOCIATED_FOB_ID"  ,  
          "attributeValue"  :     "1000"  
        },     {  
          "attributeName"  :     "CPN_SEO_DESCRIPTION"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_KEYWORDS"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_TITLE"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "IS_OFFERS_ELIGIBLE"  ,  
          "attributeValue"  :     "N"  
        }]  
      }  
    },     {  
      "coupon"  :     {  
        "couponId"  :     262  ,  
        "couponUrl"  :     "http://www1.macys.com/cms/deals/CAMPUS_AMBASSADOR_15percent_off_W3060163_SCHOOL15"  ,  
        "couponHeading"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  ,  
        "couponDescription"  :     "Outdoor_Pass"  ,  
        "couponShortCode"  :     "SCHOOL15 "  ,  
        "couponNumber"  :     "00030492100318133415 "  ,  
        "couponType"  :     "Other"  ,  
        "couponEffectiveDay"  :     1  ,  
        "couponEffectiveMonth"  :     8  ,  
        "couponEffectiveYear"  :     2013  ,  
        "couponExpirationDay"  :     31  ,  
        "couponExpirationMonth"  :     10  ,  
        "couponExpirationYear"  :     2013  ,  
        "displayStartDate"  :     "2013-08-01T00:00:00-04:00"  ,  
        "displayEndDate"  :     "2013-10-31T00:00:00-04:00"  ,  
        "couponAttributes"  :     [{  
          "attributeName"  :     "CPN_ASSOCIATED_FOB_ID"  ,  
          "attributeValue"  :     "1000"  
        },     {  
          "attributeName"  :     "CPN_SEO_DESCRIPTION"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_KEYWORDS"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "CPN_SEO_TITLE"  ,  
          "attributeValue"  :     "CAMPUS_AMBASSADOR_Outdoor_Pass"  
        },     {  
          "attributeName"  :     "IS_OFFERS_ELIGIBLE"  ,  
          "attributeValue"  :     "N"  
        }]  
      }  
    }]  
  }

Error Codes

Call Specific Error Codes:

NONE

General Error Handling Documentation:

Click Here