paapi

README

go-paapi

Go SDK for Amazon product advertising. It talks to Creators API only — Amazon's replacement for the retired Product Advertising API 5 (PA-API).

The Laravel counterpart is tims/laravel-paapi. Use that in Laravel apps; use this package in Go.

PA-API 5 was not updated in place. Amazon deprecated it and replaced it with Creators API. Old webservices.amazon.* calls now return HTTP 403. See the PA-API 5 deprecation notice.

Requirements

• Go 1.21+
• Amazon Associates Creators API credentials (Credential ID, Secret, Version)

go get github.com/timslabs/go-paapi

Authentication

Create credentials in Associates Central. The SDK fetches an OAuth2 access token and attaches it as Authorization: Bearer {token} (2.x credentials also send , Version {version}).

import (
	paapi "github.com/timslabs/go-paapi"
)

client := paapi.NewClient(
	os.Getenv("PAAPI_CREDENTIAL_ID"),
	os.Getenv("PAAPI_CREDENTIAL_SECRET"),
	os.Getenv("PAAPI_CREDENTIAL_VERSION"), // e.g. 3.1
)
client.SetPartnerTag(os.Getenv("PAAPI_PARTNER_TAG"))
client.SetMarketplace("www.amazon.com")

// Token is fetched automatically on the first authenticated call.
// Or authenticate explicitly:
if err := client.Authenticate(); err != nil {
	log.Fatal(err)
}

Or manage the token yourself:

client := paapi.NewClientWithToken(os.Getenv("PAAPI_ACCESS_TOKEN"), "3.1")

Region	Version	Token endpoint	Marketplaces
NA	3.1 (or 2.1)	api.amazon.com/auth/o2/token	US, CA, MX, BR
EU	3.2 (or 2.2)	api.amazon.co.uk/auth/o2/token	UK, DE, FR, IT, ES, NL, BE, EG, IN, IE, PL, SA, SE, TR, AE
FE	3.3 (or 2.3)	api.amazon.co.jp/auth/o2/token	JP, SG, AU

3.x uses Login with Amazon (JSON body). 2.x uses Cognito (form-encoded). Tokens are cached in memory until shortly before expiry.

Quick start

package main

import (
	"fmt"
	"log"
	"os"

	paapi "github.com/timslabs/go-paapi"
	"github.com/timslabs/go-paapi/constants"
)

func main() {
	client := paapi.NewClient(
		os.Getenv("PAAPI_CREDENTIAL_ID"),
		os.Getenv("PAAPI_CREDENTIAL_SECRET"),
		os.Getenv("PAAPI_CREDENTIAL_VERSION"),
	)
	client.SetPartnerTag(os.Getenv("PAAPI_PARTNER_TAG"))
	client.SetMarketplace("www.amazon.com")

	items, err := client.Catalog.GetItems(map[string]interface{}{
		"itemIds": []string{"B0XXXX"},
		"resources": []string{
			constants.RESOURCE_ITEM_INFO_TITLE,
			constants.RESOURCE_IMAGES_PRIMARY_MEDIUM,
			constants.RESOURCE_OFFERS_V2_LISTINGS_PRICE,
		},
	}, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%v\n", items)

	search, err := client.Catalog.SearchItems(map[string]interface{}{
		"keywords":    "echo",
		"searchIndex": "All",
		"itemPage":    1,
	}, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%v\n", search)
}

Successful responses are map[string]interface{} (decoded JSON). Failed HTTP responses return typed errors from the errors package (BadRequestError, ServerError, AuthError).

All resource methods accept an optional extraHeaders map[string]string as the last argument.

If resources or partnerTag are omitted on catalog calls, the SDK fills the same defaults as tims/laravel-paapi.

Configuration

client := paapi.NewClient(id, secret, version)
client.SetTimeout(60)                 // seconds
client.SetUserAgent("MyApp/1.0")
client.AddHeaders(map[string]string{
	"X-Custom": "value",
})
client.SetPartnerTag("yourtag-20")
client.SetMarketplace("www.amazon.in")
client.SetBaseURL("https://creatorsapi.amazon") // default

Override marketplace on a single call:

resp, err := client.Catalog.SearchItems(map[string]interface{}{
	"keywords":    "tea",
	"searchIndex": "All",
}, map[string]string{"x-marketplace": "www.amazon.in"})

Base URL: https://creatorsapi.amazon

API groups

Resource	Coverage
Catalog	GetItems, SearchItems, GetVariations, GetBrowseNodes
Feed	List feeds, get feed download URL
Report	List reports, get report download URL

Package layout

go-paapi/
  client.go          # NewClient, resource wiring
  version.go
  constants/         # URLs, headers, status codes, resource strings
  errors/            # BadRequestError, ServerError, AuthError
  requests/          # HTTP Post + OAuth2 token manager
  resources/         # API resource methods
  documents/         # Per-resource usage examples
  testdata/          # JSON fixtures for tests
  utils/             # Test helpers

Tests

go test ./...
go test ./... -v
go test ./resources -run TestCatalogGetItems -v

Related

• Laravel: tims/laravel-paapi
• PHP SDK: tims/amazon-creatorsapi-php-sdk
• Creators API docs

License

MIT

Documentation

Index

• Constants
• type Client
  • func NewClient(credentialID, credentialSecret, version string) *Client
  • func NewClientWithToken(token, version string) *Client
  • func (client *Client) AddHeaders(headers map[string]string)
  • func (client *Client) Authenticate() error
  • func (client *Client) SetAuthEndpoint(authEndpoint string)
  • func (client *Client) SetBaseURL(baseURL string)
  • func (client *Client) SetMarketplace(marketplace string)
  • func (client *Client) SetPartnerTag(partnerTag string)
  • func (client *Client) SetTimeout(timeout int16)
  • func (client *Client) SetUserAgent(userAgent string)

Constants

const SDKName = "go-paapi"

SDKName is the name of this SDK.

const SDKVersion = "0.1.0"

SDKVersion is the current package version.

Types

type Client

type Client struct {
	*requests.Request
	Catalog *resources.Catalog
	Feed    *resources.Feed
	Report  *resources.Report
}

Client provides helper methods to call Amazon Creators API.

func NewClient

func NewClient(credentialID, credentialSecret, version string) *Client

NewClient creates a Creators API client using OAuth client credentials. The access token is obtained lazily on the first authenticated request (or via Authenticate).

func NewClientWithToken

func NewClientWithToken(token, version string) *Client

NewClientWithToken creates a client that uses an existing OAuth access token.

func (*Client) AddHeaders

func (client *Client) AddHeaders(headers map[string]string)

AddHeaders adds additional headers to all subsequent requests.

func (*Client) Authenticate

func (client *Client) Authenticate() error

Authenticate obtains an OAuth2 access token using the credentials passed to NewClient.

func (*Client) SetAuthEndpoint

func (client *Client) SetAuthEndpoint(authEndpoint string)

SetAuthEndpoint overrides the OAuth2 token URL (useful in tests).

func (*Client) SetBaseURL

func (client *Client) SetBaseURL(baseURL string)

SetBaseURL overrides the API host (useful in tests).

func (*Client) SetMarketplace

func (client *Client) SetMarketplace(marketplace string)

SetMarketplace sets the x-marketplace header (for example www.amazon.in).

func (*Client) SetPartnerTag

func (client *Client) SetPartnerTag(partnerTag string)

SetPartnerTag sets the Associates tracking ID injected into catalog requests.

func (*Client) SetTimeout

func (client *Client) SetTimeout(timeout int16)

SetTimeout sets the HTTP timeout in seconds.

func (*Client) SetUserAgent

func (client *Client) SetUserAgent(userAgent string)

SetUserAgent sets a custom User-Agent prefix.