NOTE: This README explains the main branch, which may contain unreleased code. For the README of the latest release, please refer to this link.
Peddler is a Ruby interface to the Amazon Selling Partner API (SP-API). The SP-API enables Amazon sellers and vendors to programmatically access their data on orders, shipments, payments, and more.
Peddler is automatically generated from the Open API models provided by Amazon.
To begin using the Amazon SP-API, you must register as a developer and register your application. Once registered, obtain your Login with Amazon (LWA) credentials to access your own or other selling partners' data.
Add this line to your Gemfile.
gem "peddler", "~> 4.0"And then execute:
bundle installSet your LWA credentials in your environment.
export LWA_CLIENT_ID=<YOUR_CLIENT_ID>
export LWA_CLIENT_SECRET=<YOUR_CLIENT_SECRET>Require the library.
require "peddler"A seller or vendor provides you a refresh token to access their data on Amazon.
refresh_token = Peddled::Token.request(
code: "<AUTHORIZATION_CODE>"
).parse["refresh_token"]You use this to generate a temporary access token to authenticate individual API requests.
access_token = Peddler::Token.request(
refresh_token: "<REFRESH_TOKEN>",
).parse["access_token"]Similarly, you can request a token for grantless operations.
access_token = Peddler::Token.request(
scope: "sellingpartnerapi::notifications",
).parse["access_token"]If you haven’t set your LWA credentials as environment variables, pass them directly when requesting the token.
access_token = Peddler::Token.request(
client_id: "<YOUR_CLIENT_ID>",
client_secret: "<YOUR_CLIENT_SECRET>",
refresh_token: "<REFRESH_TOKEN>",
).parse["access_token"]Access tokens are valid for one hour. To optimize performance, cache the token and reuse across calls.
In Rails, if you're storing a refresh token in a model representing a selling partner, implement a method there to retrieve and cache access tokens:
class Seller
"..."
def access_token
Rails.cache.fetch("#{cache_key}/access_key", expires_in: 1.hour) do
Peddler::Token.request(
refresh_token:,
).parse["access_token"]
end
end
endAmazon’s Selling Partner API (SP-API) imposes rate limits on most operations. Peddler respects these limits and will automatically back off when throttled. You can override the default rate limit by passing a :rate_limit to the operation.
You can also provide an optional :retries argument when initializing an API to specify the number of retries if throttled. By default, this is set to 0, meaning no retries will be attempted. If set to a positive value, Peddler will retry the request that many times if throttled, backing off based on the specified rate limit.
Note: This functionality requires version 6 of the underlying HTTP library. As of writing, this is not released yet. To use rate limiting, point to their main branch on GitHub.
Example usage:
api = Peddler.orders_v0(aws_region, access_token, retries: 3)
api.get_orders(
marketplaceIds: ["ATVPDKIKX0DER"],
createdAfter: "2023-01-01T00:00:00Z"
)In this example, if the request to get_orders is throttled, Peddler will retry the request up to 3 times, backing off according to the rate limit specified by Amazon.
Peddler provides a class for each API version under an eponymous namespace. Below is a list of the more important APIs, along with brief descriptions and code examples to help you get started.
Provides programmatic access to Amazon's catalog data, such as item titles, descriptions, and other product details.
api = Peddler.catalog_items_2022_04_01(aws_region, access_token)
response = api.get_catalog_item(
marketplaceIds: ["ATVPDKIKX0DER"],
asin: "B08N5WRWNW"
)
items = response.dig("items")Allows you to retrieve order information, including order details, buyer information, and order items.
api = Peddler.orders_v0(aws_region, access_token)
response = api.get_orders(
marketplaceIds: ["ATVPDKIKX0DER"],
createdAfter: "2023-01-01T00:00:00Z"
)
response.dig("orders")Enables you to upload data to Amazon for updating listings, prices, inventory, and more.
api = Peddler.feeds_2021_06_30(aws_region, access_token)
# Create a feed document to get an upload URL
response = api.create_feed_document(
contentType: "text/xml; charset=UTF-8"
)
feed_document_id = response.parse["feedDocumentId"]
upload_url = response.parse["url"]
# Upload the feed content to the provided URL
feed_content = File.read("inventory_update.xml")
api.upload_feed_document(upload_url, feed_content, "text/xml; charset=UTF-8")
# Create the feed
response = api.create_feed(
feedType: "POST_INVENTORY_AVAILABILITY_DATA",
marketplaceIds: ["ATVPDKIKX0DER"],
inputFeedDocumentId: feed_document_id
)
response.parse["feedId"]Allows you to request and download various reports, such as order and inventory reports.
api = Peddler.reports_2021_06_30(aws_region, access_token)
response = api.create_report(
reportType: "GET_FLAT_FILE_OPEN_LISTINGS_DATA",
marketplaceIds: ["ATVPDKIKX0DER"]
)
response.parse["reportId"]Enables you to manage your product listings on Amazon, including creating, updating, and deleting listings.
api = Peddler.listings_items_2021_08_01(aws_region, access_token)
response = api.put_listings_item(
"<SELLER_ID>",
"SKU123",
"ATVPDKIKX0DER",
body: {
productType: "PRODUCT",
requirements: "LISTING",
attributes: {
title: [{ value: "New Product Title" }],
description: [{ value: "Product description goes here." }],
bullet_point: [{ value: "Feature 1" }, { value: "Feature 2" }],
manufacturer: [{ value: "Your Brand" }]
}
}
)
response.parseAllows you to subscribe to notifications for specific events like order status updates or feed processing statuses.
api = Peddler.notifications_v1(aws_region, access_token)
# Create a destination
response = api.create_destination(
name: "MySQSQueue",
resourceSpecification: {
sqs: {
arn: "arn:aws:sqs:us-east-1:123456789012:MyQueue"
}
}
)
destination_id = response.parse["destinationId"]
# Create a subscription
response = api.create_subscription(
notificationType: "ANY_OFFER_CHANGED",
destinationId: destination_id
)
subscription = response.parseProvides information about fees that may be charged for selling products on Amazon.
api = Peddler.product_fees_v0(aws_region, access_token)
response = api.get_my_fees_estimate_for_sku(
sellerId: "<YOUR_SELLER_ID>",
sku: "SKU123",
body: {
FeesEstimateRequest: {
MarketplaceId: "ATVPDKIKX0DER",
IsAmazonFulfilled: true,
PriceToEstimateFees: {
ListingPrice: {
CurrencyCode: "USD",
Amount: 25.00
}
}
}
}
)
fees_estimate = response.parseAllows you to create and manage fulfillment orders using Amazon's fulfillment network.
api = Peddler.fulfillment_outbound_2020_07_01(aws_region, access_token)
response = api.create_fulfillment_order(
body: {
sellerFulfillmentOrderId: "ORDER123",
displayableOrderId: "ORDER123",
displayableOrderDate: Time.now.iso8601,
displayableOrderComment: "Thank you for your order!",
shippingSpeedCategory: "Standard",
destinationAddress: {
name: "John Doe",
addressLine1: "123 Main St",
city: "Anytown",
stateOrRegion: "NY",
postalCode: "12345",
countryCode: "US"
},
items: [
{
sellerSku: "SKU123",
sellerFulfillmentOrderItemId: "ITEM123",
quantity: 1
}
]
}
)
response.parseAllows you to create shipping labels for orders using Amazon's negotiated shipping rates.
api = Peddler.merchant_fulfillment_v0(aws_region, access_token)
response = api.get_eligible_shipping_services(
body: {
shipmentRequestDetails: {
amazonOrderId: "ORDER123",
itemList: [
{
orderItemId: "ITEM123",
quantity: 1
}
],
shipFromAddress: {
name: "Your Company",
addressLine1: "123 Warehouse Ave",
city: "Anytown",
stateOrRegion: "NY",
postalCode: "12345",
countryCode: "US"
},
packageDimensions: {
length: 10,
width: 5,
height: 8,
unit: "INCHES"
},
weight: {
value: 2,
unit: "POUNDS"
},
shippingServiceOptions: {
deliveryExperience: "DELIVERY_CONFIRMATION_WITHOUT_SIGNATURE",
carrierWillPickUp: false
}
}
}
)
shipping_services = response.parse["shippingServiceList"]Allows vendors to retrieve purchase orders and order details from Amazon.
api = Peddler.vendor_orders_2021_12_28(aws_region, access_token)
response = api.get_purchase_orders(
shipToPartyId: "<PARTY_ID>",
limit: 10,
createdAfter: "2023-01-01T00:00:00Z"
)
purchase_orders = response.parse["purchaseOrders"]Enables vendors to manage shipping labels and shipping information for direct fulfillment orders.
api = Peddler.vendor_direct_fulfillment_shipping_2021_12_28(aws_region, access_token)
response = api.get_packing_slip(
purchaseOrderNumber: "PO123456789"
)
response.parseAllows vendors to receive orders for direct fulfillment and provide shipment confirmations.
api = Peddler.vendor_direct_fulfillment_orders_2021_12_28(aws_region, access_token)
response = api.get_orders(
createdAfter: "2023-01-01T00:00:00Z",
limit: 10
)
response.parse["orders"]Enables vendors to update inventory levels for direct fulfillment items.
api = Peddler.vendor_direct_fulfillment_inventory_2021_12_28(aws_region, access_token)
response = api.submit_inventory_update(
body: {
inventory: [
{
sellingParty: {
partyId: "<PARTY_ID>"
},
warehouseId: "<WAREHOUSE_ID>",
items: [
{
buyerProductIdentifier: "B08N5WRWNW",
availableQuantity: {
amount: 100,
unitOfMeasure: "Each"
}
}
]
}
]
}
)
response.parseProvides functionalities for purchasing shipping labels and tracking shipments.
api = Peddler.shipping_v2(aws_region, access_token)
response = api.purchase_shipment(
body: {
clientReferenceId: "CLIENT_REF_123",
shipTo: {
name: "John Doe",
addressLine1: "123 Main St",
city: "Anytown",
stateOrRegion: "NY",
postalCode: "12345",
countryCode: "US"
},
shipFrom: {
name: "Your Company",
addressLine1: "123 Warehouse Ave",
city: "Anytown",
stateOrRegion: "NY",
postalCode: "12345",
countryCode: "US"
},
packages: [
{
dimensions: {
length: 10,
width: 5,
height: 8,
unit: "IN"
},
weight: {
value: 2,
unit: "LB"
}
}
],
serviceType: "Standard"
}
)
response.parseAllows you to create restricted data tokens to access personally identifiable information (PII) in specific API calls.
api = Peddler.tokens_2021_03_01(aws_region, access_token)
response = api.create_restricted_data_token(
body: {
restrictedResources: [
{
method: "GET",
path: "/orders/v0/orders/123-1234567-1234567",
dataElements: ["buyerInfo", "shippingAddress"]
}
]
}
)
restricted_data_token = response.parse["restrictedDataToken"]
# Use the token in subsequent API calls
orders_api = Peddler.orders_2021_12_01("<AWS_REGION>", restricted_data_token)
response = orders_api.get_order(
orderId: "123-1234567-1234567"
)
response.parseProvides information about financial events for your seller account, such as order payments, refunds, and fees.
api = Peddler.finances_v0(aws_region, access_token)
response = api.list_financial_events(
postedAfter: "2023-01-01T00:00:00Z",
maxResultsPerPage: 100
)
response.parseProvides information about seller's marketplaces and participation status.
api = Peddler.sellers_v1(aws_region, access_token)
response = api.get_marketplace_participations
response.parse- Code generate payload parsers.
- Code generate the APIs section—descriptions and code examples—in this README here.
- Schedule code generation with GitHub Actions. Push new gem when models change.
- Review and consider applying these patches.
