amz-advertising-api

v2.0.0

Published

3 years ago

This class helps you interfacing the Amazon Advertising API.

Downloads

0High
0Medium
0Low

humanstupidity

amazon api advertising nodejs amz

Synopsis

Amazon Advertising API NodeJS client library.

Documentation

API Reference Access Request Getting Started

Tutorials

Register Sandbox Profile - This tutorial will show you how to register a profile in sandbox using CURL. Generate and download a report using CURL - You will need to complete registering a profile in sandbox prior to doing this tutorial.

Sandbox self-service

If you would like to test the API in sandbox you will need to register a profile for the region in which you would like to test. The registerProfile API call can be made to do this. Make sure you instantiate the client in sandbox mode before making this call or it will fail. The following country codes are available for testing.

US, CA, UK, DE, FR, ES, IT, IN, CN, JP

client.registerProfile({"countryCode": "IT"});

{
  "registerProfileId": "5cf1aca5-4ab8-4489-8c33-013d1f85c586JP",
  "status": "IN_PROGRESS",
  "statusDetails": "Registration workflow has been started"
}

Quick Start

Instantiate the client

You can pass in profileId later. You can get all available profiles with listProfiles. After you instantiate the client you have to call init().


let AdvertisingClient = require('amz-advertising-api');

let config = {
    clientId: "CLIENT_ID",
    clientSecret: "CLIENT_SECRET",
    accessToken: "ACCESS_TOKEN",
    refreshToken: "REFRESH_TOKEN",
    profileId: "PROFILE_ID",
    sandbox: false,
    region: 'eu'
}

let client = new AdvertisingClient(config);

await client.init();

Refresh access token

The refresh token gets automaticly refreshed every 2 minutes.

{
  "access_token": "Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR…",
  "expires_in": 3600
}

Get a list of profiles

let profiles = await client.listProfiles();

[
  {
    "profileId":1234567890,
    "countryCode":"US",
    "currencyCode":"USD",
    "dailyBudget":10.00,
    "timezone":"America/Los_Angeles",
    "accountInfo":{
      "marketplaceStringId":"ABC123",
      "sellerStringId":"DEF456"
    }
  }
]

Set profile Id

client.options.profileId = "1234567890";

Once you've set the profile Id you are ready to start making API calls.

Example API Calls

getProfile

Retrieves a single profile by Id.

await client.getProfile("1234567890");

{
  "profileId": 1234567890,
  "countryCode": "US",
  "currencyCode": "USD",
  "dailyBudget": 3.99,
  "timezone": "America/Los_Angeles",
  "accountInfo": {
    "marketplaceStringId": "ABC123",
    "sellerStringId": "DEF456"
  }
}

updateProfiles

Updates one or more profiles. Advertisers are identified using their profileIds.

await client.updateProfiles(
  [
    {
      "profileId": client.profileId,
      "dailyBudget": 3.99
    },
    {
      "profileId": 11223344,
      "dailyBudget": 6.00
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "profileId": 1234567890
  },
  {
    "code": "NOT_FOUND",
    "description": "Profile with id 11223344 was not found for this advertiser.",
    "profileId": 0
  }
]

listCampaigns

Retrieves a list of campaigns satisfying optional criteria.

await client.listCampaigns({"stateFilter": "enabled"});

[
  {
    "campaignId": 59836775211065,
    "name": "CampaignOne",
    "campaignType": "sponsoredProducts",
    "targetingType": "manual",
    "dailyBudget": 15.0,
    "startDate": "20160330",
    "state": "enabled"
  },
  {
    "campaignId": 254238342004647,
    "name": "CampaignTwo",
    "campaignType": "sponsoredProducts",
    "targetingType": "manual",
    "dailyBudget": 5.0,
    "startDate": "20160510",
    "state": "enabled"
  }
]

getCampaign

Retrieves a campaign by Id. Note that this call returns the minimal set of campaign fields, but is more efficient than getCampaignEx.

await client.getCampaign(1234567890);

{
  "campaignId": 1234567890,
  "name": "CampaignOne",
  "campaignType": "sponsoredProducts",
  "targetingType": "manual",
  "dailyBudget": 15.0,
  "startDate": "20160330",
  "state": "enabled"
}

createCampaigns

Creates one or more campaigns. Successfully created campaigns will be assigned unique campaignIds.

await client.createCampaigns(
  [
    {
      "name": "My Campaign One",
      "campaignType": "sponsoredProducts",
      "targetingType": "manual",
      "state": "enabled",
      "dailyBudget": 5.00,
      "startDate": date("Ymd")
    },
    {
      "name": "My Campaign Two",
      "campaignType": "sponsoredProducts",
      "targetingType": "manual",
      "state": "enabled",
      "dailyBudget": 15.00,
      "startDate": date("Ymd")
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "campaignId": 173284463890123
  },
  {
    "code": "SUCCESS",
    "campaignId": 27074907785456
  }
]

updateCampaigns

Updates one or more campaigns. Campaigns are identified using their campaignIds.

await client.updateCampaigns(
  [
    {
      "campaignId": 173284463890123,
      "name": "Update Campaign One",
      "state": "enabled",
      "dailyBudget": 10.99
    },
    {
      "campaignId": 27074907785456,
      "name": "Update Campaign Two",
      "state": "enabled",
      "dailyBudget": 99.99
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "campaignId": 173284463890123
  },
  {
    "code": "SUCCESS",
    "campaignId": 27074907785456
  }
]

archiveCampaign

Sets the campaign status to archived. This same operation can be performed via an update, but is included for completeness.

await client.archiveCampaign(1234567890);

{
  "code": "SUCCESS",
  "campaignId": 1234567890
}

listCampaignsBrand

Retrieves a list of campaigns satisfying optional criteria. Used for Sponsored Brands.

await client.listCampaignsBrand({"stateFilter": "enabled"});

[
  {
    "campaignId": 59836775211065,
    "name": "CampaignOne",
    "campaignType": "sponsoredProducts",
    "targetingType": "manual",
    "dailyBudget": 15.0,
    "startDate": "20160330",
    "state": "enabled"
  },
  {
    "campaignId": 254238342004647,
    "name": "CampaignTwo",
    "campaignType": "sponsoredProducts",
    "targetingType": "manual",
    "dailyBudget": 5.0,
    "startDate": "20160510",
    "state": "enabled"
  }
]

getCampaignBrand

Retrieves a campaign by Id. Used for Sponsored Brands.

await client.getCampaignBrand(1234567890);

{
  "campaignId": 1234567890,
  "name": "CampaignOne",
  "campaignType": "sponsoredProducts",
  "targetingType": "manual",
  "dailyBudget": 15.0,
  "startDate": "20160330",
  "state": "enabled"
}

updateCampaignsBrand

Updates one or more campaigns. Campaigns are identified using their campaignIds. Used for Sponsored Brands.

await client.updateCampaignsBrand(
  [
    {
      "campaignId": 173284463890123,
      "name": "Update Campaign One",
      "state": "enabled",
      "dailyBudget": 10.99
    },
    {
      "campaignId": 27074907785456,
      "name": "Update Campaign Two",
      "state": "enabled",
      "dailyBudget": 99.99
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "campaignId": 173284463890123
  },
  {
    "code": "SUCCESS",
    "campaignId": 27074907785456
  }
]

archiveCampaignBrand

Sets the campaign status to archived. This same operation can be performed via an update, but is included for completeness. Used for Sponsored Brands.

await client.archiveCampaignBrand(1234567890);

{
  "code": "SUCCESS",
  "campaignId": 1234567890
}

listAdGroups

Retrieves a list of ad groups satisfying optional criteria.

await client.listAdGroups({"stateFilter": "enabled"});

[
  {
    "adGroupId": 262960563101486,
    "name": "AdGroup One",
    "campaignId": 181483024866689,
    "defaultBid": 1.0,
    "state": "enabled"
  },
  {
    "adGroupId": 52169162825843,
    "name": "AdGroup Two",
    "campaignId": 250040549047739,
    "defaultBid": 2.0,
    "state": "enabled"
  }
]

getAdGroup

Retrieves an ad group by Id. Note that this call returns the minimal set of ad group fields, but is more efficient than getAdGroupEx.

await client.getAdGroup(262960563101486);

{
  "adGroupId": 262960563101486,
  "name": "AdGroup One",
  "campaignId": 181483024866689,
  "defaultBid": 1.0,
  "state": "enabled"
}

createAdGroups

Creates one or more ad groups. Successfully created ad groups will be assigned unique adGroupIds.

await client.createAdGroups(
  [       
    {
      "campaignId": 250040549047739,
      "name": "New AdGroup One",
      "state": "enabled",
      "defaultBid": 2.0
    },
    {
      "campaignId": 59836775211065,
      "name": "New AdGroup Two",
      "state": "enabled",
      "defaultBid": 5.0
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "adGroupId": 117483076163518
  },
  {
    "code": "SUCCESS",
    "adGroupId": 123431426718271
  }
]

updateAdGroups

Updates one or more ad groups. Ad groups are identified using their adGroupIds.

await client.updateAdGroups(
  [
    {
      "adGroupId": 117483076163518,
      "state": "enabled",
      "defaultBid": 20.0
    },
    {
      "adGroupId": 123431426718271,
      "state": "enabled",
      "defaultBid": 15.0
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "adGroupId": 117483076163518
  },
  {
    "code": "SUCCESS",
    "adGroupId": 123431426718271
  }
]

archiveAdGroup

Sets the ad group status to archived. This same operation can be performed via an update, but is included for completeness.

await client.archiveAdGroup(117483076163518);

{
  "code": "SUCCESS",
  "adGroupId": 117483076163518
}

listBiddableKeywords

Retrieves a list of keywords satisfying optional criteria.

await client.listBiddableKeywords({"stateFilter": "enabled"});

[
  {
    "keywordId": 174140697976855,
    "adGroupId": 52169162825843,
    "campaignId": 250040549047739,
    "keywordText": "KeywordOne",
    "matchType": "exact",
    "state": "enabled"
  },
  {
    "keywordId": 118195812188994,
    "adGroupId": 52169162825843,
    "campaignId": 250040549047739,
    "keywordText": "KeywordTwo",
    "matchType": "exact",
    "state": "enabled"
  }
]

getBiddableKeyword

Retrieves a keyword by Id. Note that this call returns the minimal set of keyword fields, but is more efficient than getBiddableKeywordEx.

await client.getBiddableKeyword(174140697976855);

{
  "keywordId": 174140697976855,
  "adGroupId": 52169162825843,
  "campaignId": 250040549047739,
  "keywordText": "KeywordOne",
  "matchType": "exact",
  "state": "enabled"
}

createBiddableKeywords

Creates one or more keywords. Successfully created keywords will be assigned unique keywordIds.

await client.createBiddableKeywords(
  [
    {
      "campaignId": 250040549047739,
      "adGroupId": 52169162825843,
      "keywordText": "AnotherKeyword",
      "matchType": "exact",
      "state": "enabled"
    },
    {
      "campaignId": 250040549047739,
      "adGroupId": 52169162825843,
      "keywordText": "YetAnotherKeyword",
      "matchType": "exact",
      "state": "enabled"
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "keywordId": 112210768353976
  },
  {
    "code": "SUCCESS",
    "keywordId": 249490346605943
  }
]

updateBiddableKeywords

Updates one or more keywords. Keywords are identified using their keywordIds.

await client.updateBiddableKeywords(
  [
    {
      "keywordId": 112210768353976,
      "bid": 100.0,
      "state": "archived"
    },
    {
      "keywordId": 249490346605943,
      "bid": 50.0,
      "state": "archived"
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "keywordId": 112210768353976
  },
  {
    "code": "SUCCESS",
    "keywordId": 249490346605943
  }
]

archiveBiddableKeyword

Sets the keyword status to archived. This same operation can be performed via an update, but is included for completeness.

await client.archiveBiddableKeyword(112210768353976);

{
  "code": "200",
  "requestId": "0TR95PJD6Z16FFCZDXD0"
}

getBiddableKeywordBrand

Retrieves a keyword by Id. Note that this call returns the minimal set of keyword fields, but is more efficient than getBiddableKeywordEx. Used for Sponsored Brands.

await client.getBiddableKeywordBrand(174140697976855);

{
  "keywordId": 174140697976855,
  "adGroupId": 52169162825843,
  "campaignId": 250040549047739,
  "keywordText": "KeywordOne",
  "matchType": "exact",
  "state": "enabled"
}

createBiddableKeywordsBrand

Creates one or more keywords. Successfully created keywords will be assigned unique keywordIds. Used for Sponsored Brands.

await client.createBiddableKeywordsBrand(
  [
    {
      "campaignId": 250040549047739,
      "adGroupId": 52169162825843,
      "keywordText": "AnotherKeyword",
      "matchType": "exact",
      "state": "enabled"
    },
    {
      "campaignId": 250040549047739,
      "adGroupId": 52169162825843,
      "keywordText": "YetAnotherKeyword",
      "matchType": "exact",
      "state": "enabled"
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "keywordId": 112210768353976
  },
  {
    "code": "SUCCESS",
    "keywordId": 249490346605943
  }
]

updateBiddableKeywordsBrand

Updates one or more keywords. Keywords are identified using their keywordIds. Used for Sponsored Brands.

await client.updateBiddableKeywordsBrand(
  {
    {
      "keywordId": 112210768353976,
      "bid": 100.0,
      "state": "archived"
    },
    {
      "keywordId": 249490346605943,
      "bid": 50.0,
      "state": "archived"
    }
  }
);

[
  {
    "code": "SUCCESS",
    "keywordId": 112210768353976
  },
  {
    "code": "SUCCESS",
    "keywordId": 249490346605943
  }
]

archiveBiddableKeywordBrand

Sets the keyword status to archived. This same operation can be performed via an update, but is included for completeness. Used for Sponsored Brands.

await client.archiveBiddableKeywordBrand(112210768353976);

{
  "code": "200",
  "requestId": "0TR95PJD6Z16FFCZDXD0"
}

listNegativeKeywords

Retrieves a list of negative keywords satisfying optional criteria.

await client.listNegativeKeywords({"stateFilter": "enabled"});

[
  {
    "keywordId": 281218602770639,
    "adGroupId": 52169162825843,
    "campaignId": 250040549047739,
    "keywordText": "KeywordOne",
    "matchType": "negativeExact",
    "state": "enabled"
  },
  {
    "keywordId": 280875877064090,
    "adGroupId": 262960563101486,
    "campaignId": 181483024866689,
    "keywordText": "KeywordTwo",
    "matchType": "negativeExact",
    "state": "enabled"
  }
]

getNegativeKeyword

Retrieves a negative keyword by Id. Note that this call returns the minimal set of keyword fields, but is more efficient than getNegativeKeywordEx.

await client.getNegativeKeyword(281218602770639);

{
  "keywordId": 281218602770639,
  "adGroupId": 52169162825843,
  "campaignId": 250040549047739,
  "keywordText": "KeywordOne",
  "matchType": "negativeExact",
  "state": "enabled"
}

createNegativeKeywords

Creates one or more negative keywords. Successfully created keywords will be assigned unique keywordIds.

await client.createNegativeKeywords(
  [
    {
      "campaignId": 250040549047739,
      "adGroupId": 52169162825843,
      "keywordText": "AnotherKeyword",
      "matchType": "negativeExact",
      "state": "enabled"
    },
    {
      "campaignId": 181483024866689,
      "adGroupId": 262960563101486,
      "keywordText": "YetAnotherKeyword",
      "matchType": "negativeExact",
      "state": "enabled"
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "keywordId": 61857817062026
  },
  {
    "code": "SUCCESS",
    "keywordId": 147623067066967
  }
]

updateNegativeKeywords

Updates one or more negative keywords. Keywords are identified using their keywordIds.

await client.updateNegativeKeywords(
  [
    {
      "keywordId": 61857817062026,
      "state": "enabled",
      "bid": 15.0
    },
    {
      "keywordId": 61857817062026,
      "state": "enabled",
      "bid": 20.0
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "keywordId": 61857817062026
  },
  {
    "code": "INVALID_ARGUMENT",
    "description": "Entity with id 61857817062026 already specified in this update operation."
  }
]

archiveNegativeKeyword

Sets the negative keyword status to archived. This same operation can be performed via an update to the status, but is included for completeness.

await client.archiveNegativeKeyword(61857817062026);

{
  "code": "SUCCESS",
  "keywordId": 61857817062026
}

listCampaignNegativeKeywords

Retrieves a list of negative campaign keywords satisfying optional criteria.

await client.listCampaignNegativeKeywords({"matchTypeFilter": "negativeExact"});

[
  {
    "keywordId": 131747786239884,
    "adGroupId": null,
    "campaignId": 181483024866689,
    "keywordText": "Negative Keyword",
    "matchType": "negativeExact",
    "state": "enabled"
  },
  {
    "keywordId": 197201372210821,
    "adGroupId": null,
    "campaignId": 181483024866689,
    "keywordText": "My Negative Keyword",
    "matchType": "negativeExact",
    "state": "enabled"
  }
]

getCampaignNegativeKeyword

Retrieves a campaign negative keyword by Id. Note that this call returns the minimal set of keyword fields, but is more efficient than getCampaignNegativeKeywordEx.

await client.getCampaignNegativeKeyword(197201372210821);

{
  "keywordId": 197201372210821,
  "adGroupId": null,
  "campaignId": 181483024866689,
  "keywordText": "My Negative Keyword",
  "matchType": "negativeExact",
  "state": "enabled"
}

createCampaignNegativeKeywords

Creates one or more campaign negative keywords. Successfully created keywords will be assigned unique keywordIds.

await client.createCampaignNegativeKeywords(
  [
    {
      "campaignId": 181483024866689,
      "keywordText": "Negative Keyword One",
      "matchType": "negativeExact",
      "state": "enabled"
    },
    {
      "campaignId": 181483024866689,
      "keywordText": "Negative Keyword Two",
      "matchType": "negativeExact",
      "state": "enabled"
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "keywordId": 196797670902082
  },
  {
    "code": "SUCCESS",
    "keywordId": 186203479904657
  }
]

updateCampaignNegativeKeywords

Updates one or more campaign negative keywords. Keywords are identified using their keywordIds.

Campaign negative keywords can currently only be removed.

removeCampaignNegativeKeyword

Sets the campaign negative keyword status to deleted. This same operation can be performed via an update to the status, but is included for completeness.

await client.removeCampaignNegativeKeyword(186203479904657);

{
  "code": "SUCCESS",
  "keywordId": 186203479904657
}

listProductAds

Retrieves a list of product ads satisfying optional criteria.

await client.listProductAds({"stateFilter": "enabled"});

[
  {
    "adId": 247309761200483,
    "adGroupId": 262960563101486,
    "campaignId": 181483024866689,
    "sku": "TEST001",
    "state": "enabled"
  }
]

getProductAd

Retrieves a product ad by Id. Note that this call returns the minimal set of product ad fields, but is more efficient than getProductAdEx.

await client.getProductAd(247309761200483);

{
  "adId": 247309761200483,
  "adGroupId": 262960563101486,
  "campaignId": 181483024866689,
  "sku": "TEST001",
  "state": "enabled"
}

createProductAds

Creates one or more product ads. Successfully created product ads will be assigned unique adIds.

await client.createProductAds(
  [
    {
      "campaignId": 181483024866689,
      "adGroupId": 262960563101486,
      "sku": "TEST002",
      "state": "enabled"
    },
    {
      "campaignId": 181483024866689,
      "adGroupId": 262960563101486,
      "sku": "TEST003",
      "state": "enabled"
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "adId": 239870616623537
  },
  {
    "code": "SUCCESS",
    "adId": 191456410590622
  }
]

updateProductAds

Updates one or more product ads. Product ads are identified using their adIds.

await client.updateProductAds(
  [
    {
      "adId": 239870616623537,
      "state": "archived"
    },
    {
      "adId": 191456410590622,
      "state": "archived"
    }
  ]
);

[
  {
    "code": "SUCCESS",
    "adId": 239870616623537
  },
  {
    "code": "SUCCESS",
    "adId": 191456410590622
  }
]

archiveProductAd

Sets the product ad status to archived. This same operation can be performed via an update, but is included for completeness.

await client.archiveProductAd(239870616623537);

{
  "code": "SUCCESS",
  "adId": 239870616623537
}

requestSnapshot

Request a snapshot report for all entities of a single type.

await client.requestSnapshot(
  "campaigns",
  {
    "stateFilter": "enabled,paused,archived",
    "campaignType": "sponsoredProducts"
  }
);

{
  "snapshotId": "amzn1.clicksAPI.v1.p1.573A0477.ec41773a-1659-4013-8eb9-fa18c87ef5df",
  "recordType": "campaign",
  "status": "IN_PROGRESS"
}

getSnapshot

Retrieve a previously requested report.

await client.getSnapshot("amzn1.clicksAPI.v1.p1.573A0477.ec41773a-1659-4013-8eb9-fa18c87ef5df");

[
  {
    "campaignId": 181483024866689,
    "name": "Campaign One",
    "campaignType": "sponsoredProducts",
    "targetingType": "manual",
    "dailyBudget": 5.0,
    "startDate": "20160330",
    "state": "archived"
  },
  {
    "campaignId": 59836775211065,
    "name": "Campaign Two",
    "campaignType": "sponsoredProducts",
    "targetingType": "manual",
    "dailyBudget": 10.99,
    "startDate": "20160330",
    "state": "archived"
  },
  {
    "campaignId": 254238342004647,
    "name": "Campaign Three",
    "campaignType": "sponsoredProducts",
    "targetingType": "manual",
    "dailyBudget": 99.99,
    "startDate": "20160510",
    "state": "enabled"
  }
]

requestSnapshotBrand

Request a snapshot report for all entities of a single type. Used for Sponsored Brands.

await client.requestSnapshotBrand(
  "campaigns",
  {
    "stateFilter": "enabled,paused,archived",
    "campaignType": "sponsoredProducts"
  }
);

{
  "snapshotId": "amzn1.clicksAPI.v1.p1.573A0477.ec41773a-1659-4013-8eb9-fa18c87ef5df",
  "recordType": "campaign",
  "status": "IN_PROGRESS"
}

requestReport

Request a customized performance report for all entities of a single type which have performance data to report.

await client.requestReport(
  "campaigns",
  {
    "reportDate": "20160515",
    "campaignType": "sponsoredProducts",
    "metrics": "impressions,clicks,cost"
  }
);

{
  "reportId": "amzn1.clicksAPI.v1.m1.573A0808.32908def-66a1-4ce2-8f12-780dc4ae1d43",
  "recordType": "campaign",
  "status": "IN_PROGRESS",
  "statusDetails": "Report is submitted"
}

requestReportBrand