• Register

Promotion and Coupon Services V3

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

 

back to top

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"  
        }]  
      }  
    }]  
  } 

back to top

Error Codes

Call Specific Error Codes:

NONE

General Error Handling Documentation:

Click Here

back to top

Docs Navigation