{"id":14893221,"url":"https://github.com/lineofflight/peddler","last_synced_at":"2026-02-28T20:16:29.927Z","repository":{"id":842681,"uuid":"566934","full_name":"lineofflight/peddler","owner":"lineofflight","description":"Amazon Selling Partner API (SP-API) in Ruby","archived":false,"fork":false,"pushed_at":"2025-05-12T21:03:13.000Z","size":4380,"stargazers_count":308,"open_issues_count":0,"forks_count":130,"subscribers_count":30,"default_branch":"main","last_synced_at":"2025-05-12T21:41:01.385Z","etag":null,"topics":["amazon","ecommerce","ruby","selling-partner-api","sp-api"],"latest_commit_sha":null,"homepage":"https://lineofflight.github.io/peddler/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lineofflight.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2010-03-17T17:46:50.000Z","updated_at":"2025-05-12T21:03:16.000Z","dependencies_parsed_at":"2024-09-12T21:17:43.421Z","dependency_job_id":"0160e774-ab20-49e6-b21e-e48c1f5dc4c9","html_url":"https://github.com/lineofflight/peddler","commit_stats":{"total_commits":880,"total_committers":37,"mean_commits":"23.783783783783782","dds":0.5988636363636364,"last_synced_commit":"21746612d396bb92632c0eb483c5276758ab215f"},"previous_names":["papercavalier/peddler"],"tags_count":99,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lineofflight%2Fpeddler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lineofflight%2Fpeddler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lineofflight%2Fpeddler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lineofflight%2Fpeddler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lineofflight","download_url":"https://codeload.github.com/lineofflight/peddler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414493,"owners_count":22067271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon","ecommerce","ruby","selling-partner-api","sp-api"],"created_at":"2024-09-22T05:01:23.564Z","updated_at":"2026-02-28T20:16:29.911Z","avatar_url":"https://github.com/lineofflight.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Peddler\n\n[![Build](https://github.com/lineofflight/peddler/actions/workflows/ci.yml/badge.svg)][build]\n\nPeddler is a Ruby interface to the [Amazon Selling Partner API (SP-API)][api-docs]. The SP-API enables Amazon sellers and vendors to programmatically access their data on orders, shipments, payments, and more.\n\nPeddler is automatically generated from the latest Open API models provided by Amazon.\n\nPeddler covers all SP-API endpoints, reports, notifications, and feeds. It's also lightweight: thanks to Zeitwerk, only the code you use gets loaded.\n\nTo begin using the Amazon SP-API, you must [register as a developer][register-as-developer] and [register your application][register-application]. Once registered, [obtain your Login with Amazon (LWA) credentials][view-credentials] to access your own or other selling partners' data.\n\n- [API docs][api-docs]\n- [OpenAPI models][openapi-models]\n- [API samples][api-samples]\n\n\u003cimg src=\"https://github.com/hakanensari/peddler/blob/main/images/peddler.jpg?raw=true\" alt=\"Peddler\" style=\"max-width: 830px\" /\u003e\n\n## Installation\n\nAdd to your Gemfile.\n\n## Usage\n\n### Authorization\n\nSet your LWA credentials in your environment.\n\n```shell\nexport LWA_CLIENT_ID=\u003cYOUR_CLIENT_ID\u003e\nexport LWA_CLIENT_SECRET=\u003cYOUR_CLIENT_SECRET\u003e\n```\n\nA seller or vendor [provides you a refresh token][authorization] to access their data on Amazon.\n\n```ruby\nresponse = Peddler::LWA.request(\n  code: \"\u003cAUTHORIZATION_CODE\u003e\"\n)\nrefresh_token = response.parse.refresh_token\n```\n\nUse this to generate a temporary access token to authenticate individual requests.\n\n```ruby\nresponse = Peddler::LWA.request(\n  refresh_token: \"\u003cREFRESH_TOKEN\u003e\",\n)\naccess_token = response.parse.access_token\n```\n\nSimilarly, you can request a token for grantless operations.\n\n```ruby\nresponse = Peddler::LWA.request(\n  scope: \"sellingpartnerapi::notifications\",\n)\naccess_token = response.parse.access_token\n```\n\nIn place of environment variables, you can set them directly when requesting the token.\n\n```ruby\nresponse = Peddler::LWA.request(\n  client_id: \"\u003cYOUR_CLIENT_ID\u003e\",\n  client_secret: \"\u003cYOUR_CLIENT_SECRET\u003e\",\n  refresh_token: \"\u003cREFRESH_TOKEN\u003e\",\n)\naccess_token = response.parse.access_token\n```\n\nAccess tokens are valid for one hour. To optimize performance, cache and reuse across calls.\n\nFor example,\n\n```ruby\nclass Seller\n  attr_reader :refresh_token\n\n  def access_token\n    Rails.cache.fetch(\"#{cache_key}/access_key\", expires_in: 1.hour) do\n      Peddler::LWA.request(refresh_token:).parse.access_token\n    end\n  end\nend\n```\n\n### Rate limiting\n\nAmazon's SP-API imposes [rate limits][rate-limits] on operations. Override the default value by passing a `:rate_limit` parameter when calling an operation.\n\nProvide an optional `:retries` argument when initializing an API to specify retry attempts if throttled. Default is 0 (no retries). If set, Peddler retries with exponential backoff.\n\n```ruby\napi = Peddler.orders_v0.new(aws_region, access_token, retries: 3)\napi.get_orders(\"...\": \"...\")\n```\n\n### Typed Responses\n\nPeddler provides typed response parsing using the [Structure gem](https://github.com/hakanensari/structure), offering runtime type checking and better IDE support. Types are based on Ruby's [Data class](https://docs.ruby-lang.org/en/4.0/Data.html) and are lazy-loaded.\n\n```ruby\napi = Peddler.orders.new(aws_region, access_token)\n\n# Get orders with type-safe response\nresponse = api.get_orders(\"...\": \"...\")\n\n# Use .parse to get typed Data objects\norders = response.parse.payload.orders  # Returns array of Order Data objects\norder = orders.first\n\n# Type-safe attribute access\norder.amazon_order_id     # =\u003e \"123-4567890-1234567\"\norder.order_status        # =\u003e \"Shipped\"\norder.prime?              # =\u003e true\norder.order_total         # =\u003e Money object (automatic coercion)\norder.order_total.cents   # =\u003e 9999\norder.order_total.currency.iso_code # =\u003e \"USD\"\n```\n\n#### Hash Access\n\nIf you prefer working with plain hashes instead of typed Data objects:\n\n```ruby\napi = Peddler.orders.new(aws_region, access_token)\nresponse = api.get_orders(marketplaceIds: [\"ATVPDKIKX0DER\"])\n\n# Use .to_h to get raw Hash\norders = response.to_h[\"payload\"][\"orders\"]\n\n# Or use .dig directly (delegates to .to_h)\norders = response.dig(\"payload\", \"orders\")\n```\n\n### Error Handling\n\nAll HTTP errors (4xx and 5xx) raise `Peddler::Error` exceptions:\n\n```ruby\nbegin\n  response = api.get_orders(marketplaceIds: [\"ATVPDKIKX0DER\"])\n  orders = response.parse[\"payload\"][\"orders\"]\nrescue Peddler::Error =\u003e e\n  puts \"API Error: #{e.message}\"\n  puts \"Status: #{e.response.status}\"\n\n  # Handle retries for server errors\n  if e.response.status \u003e= 500\n    # Retry logic here\n  end\nend\n```\n\n### Available APIs\n\nPeddler provides Ruby interfaces to all Amazon SP-API endpoints. Each API is available in its respective version. Access APIs by calling methods on the Peddler module:\n\n```ruby\napi = Peddler.\u003capi_name\u003e_\u003cversion\u003e.new(aws_region, access_token, **options)\n```\n\nYou can also simply use the latest version:\n\n```ruby\napi = Peddler.\u003capi_name\u003e.new(aws_region, access_token, **options)\n```\n\nAvailable APIs by category:\n\n#### Orders and Financial APIs\n\n- **Orders API**: Retrieve and manage orders\n- **Finances API**: Financial data, payments, refunds\n- **Invoices API**: Manage billing invoices\n- **Sales API**: Order metrics and sales data\n\n```ruby\napi = Peddler.orders.new(aws_region, access_token)\nresponse = api.get_orders(\"...\": \"...\")\norders = response.parse.payload.orders\n```\n\n#### Catalog and Listing APIs\n\n- **Catalog Items API**: Access Amazon's catalog data\n- **Listings Items API**: Create and update listings\n- **Listings Restrictions API**: Check listing eligibility\n- **Product Type Definitions API**: Get schema requirements for listings\n- **A+ Content API**: Create and manage enhanced marketing content\n- **Product Pricing API**: Get pricing information\n- **Product Fees API**: Retrieve fee estimates for products\n\n```ruby\napi = Peddler.catalog_items.new(aws_region, access_token)\nresponse = api.get_catalog_item(\"...\": \"...\")\nitem = response.parse.payload\n```\n\n#### Fulfillment and Inventory APIs\n\n- **Fulfillment Inbound API**: Send inventory to FBA\n- **Fulfillment Outbound API**: Create and track FBA orders\n- **FBA Inventory API**: Manage FBA inventory quantities\n- **FBA Inbound Eligibility API**: Check product eligibility for FBA\n- **Merchant Fulfillment API**: Create shipping labels for self-fulfilled orders\n- **Easy Ship API**: Manage Amazon's carrier service\n- **Shipping APIs**: Create shipments and purchase shipping labels\n- **Replenishment API**: Manage inventory replenishment\n- **Amazon Warehousing and Distribution API**: Manage fulfillment warehousing\n- **Supply Sources API**: Manage supply/inventory sources\n- **Shipment Invoicing API**: Manage shipment-related invoices\n\n```ruby\napi = Peddler.fulfillment_outbound.new(aws_region, access_token)\nresponse = api.create_fulfillment_order(body: { \"...\": \"...\" })\n```\n\n#### Data Management APIs\n\n- **Feeds API**: Upload data to Amazon (listings, prices, inventory, etc.)\n- **Reports API**: Request and download reports (orders, inventory, fulfillment, etc.)\n- **Uploads API**: Upload files for various SP-API operations\n- **Data Kiosk API**: Access analytical data with GraphQL queries\n\n```ruby\n# Feeds API - create feed document, upload, submit\napi = Peddler.feeds.new(aws_region, access_token)\ndocument = api.create_feed_document(contentType: \"text/xml; charset=UTF-8\")\napi.upload_feed_document(document.dig(\"url\"), File.read(\"feed.xml\"), \"text/xml\")\nfeed = api.create_feed(feedType: \"POST_INVENTORY_AVAILABILITY_DATA\", marketplaceIds: [\"ATVPDKIKX0DER\"], inputFeedDocumentId: document.dig(\"feedDocumentId\"))\n```\n\n#### Data Kiosk API\n\nThe Data Kiosk API provides access to Amazon's analytical data through GraphQL queries. Peddler supports four Data Kiosk schema versions, each with type-safe classes for parsing responses.\n\n**Available Schemas:**\n\n- **SalesAndTraffic20231115**: Sales and traffic metrics by ASIN and date\n- **SalesAndTraffic20240424**: Enhanced sales and traffic data (2024)\n- **Economics20240315**: Economics and profitability data\n- **VendorAnalytics20240930**: Vendor-specific analytics and forecasting data\n\n```ruby\napi = Peddler.data_kiosk.new(aws_region, access_token)\nresponse = api.create_query(query: \"query { salesAndTrafficByDate(...) { data { date sales } } }\")\nquery_id = response.dig(\"payload\", \"queryId\")\n# Poll for completion and download document\n```\n#### Vendor APIs\n\n- **Vendor Orders API**: Retrieve purchase orders\n- **Vendor Direct Fulfillment Orders API**: Manage direct fulfillment orders\n- **Vendor Direct Fulfillment Shipping API**: Manage shipping for direct fulfillment\n- **Vendor Direct Fulfillment Payments API**: Process payments for direct fulfillment\n- **Vendor Direct Fulfillment Inventory API**: Manage inventory for direct fulfillment\n- **Vendor Direct Fulfillment Transactions API**: Track transaction status\n- **Vendor Direct Fulfillment Sandbox Test Data API**: Generate test data in sandbox\n- **Vendor Shipments API**: Track vendor shipments\n- **Vendor Invoices API**: Submit and track invoices\n- **Vendor Transaction Status API**: Check transaction status\n\n```ruby\napi = Peddler.vendor_orders.new(aws_region, access_token)\norders = api.get_purchase_orders(limit: 10, createdAfter: \"2023-01-01T00:00:00Z\").parse\n```\n\n#### Authorization and Account Management APIs\n\n- **Application Management API**: Manage application authorization\n- **Tokens API**: Generate restricted data tokens for accessing PII\n- **Sellers API**: Get seller account information and marketplace participation\n- **Services API**: Manage seller services and subscriptions\n- **Seller Wallet API**: Manage seller financial accounts\n- **Application Integrations API**: Manage app integrations\n- **Vehicles API**: Manage vehicle data for automotive products\n\n### Complex Workflows\n\nDetailed workflows are available in test files with VCR cassettes:\n\n- **Feeds API**: [test/peddler/apis/feeds_2021_06_30_test.rb](test/peddler/apis/feeds_2021_06_30_test.rb)\n- **Data Kiosk API**: [test/peddler/apis/data_kiosk_2023_11_15_test.rb](test/peddler/apis/data_kiosk_2023_11_15_test.rb)\n- **Reports API**: [lib/peddler/apis/reports_2021_06_30.rb](lib/peddler/apis/reports_2021_06_30.rb) (YARD docs)\n- **Notifications API**: [lib/peddler/notifications/](lib/peddler/notifications/) (type-safe parsing)\n\nFor complete method signatures, see [sig/peddler/apis/](sig/peddler/apis/)\n\nFor a complete list of available APIs and their detailed documentation, refer to the [API models repository][openapi-models].\n\n## Development\n\n```bash\n# Setup\nbundle install\nbundle exec rbs collection install\n\n# Run tests and linting\nbundle exec rake\n\n# Run tests only\nbundle exec rake test\n\n# Regenerate API classes from latest Amazon OpenAPI specs\nbundle exec rake generate\n\n# Type check with Steep\nbundle exec steep check --severity-level=hint\n```\n[build]: https://github.com/lineofflight/peddler/actions\n[api-docs]: https://developer.amazonservices.com/sp-api-docs/overview\n[register-as-developer]: https://developer-docs.amazon.com/sp-api/docs/registering-as-a-developer\n[register-application]: https://developer-docs.amazon.com/sp-api/docs/registering-your-application\n[openapi-models]: https://github.com/amzn/selling-partner-api-models\n[api-samples]: https://github.com/amzn/selling-partner-api-samples\n[view-credentials]: https://developer-docs.amazon.com/sp-api/docs/viewing-your-application-information-and-credentials\n[authorization]: https://developer-docs.amazon.com/sp-api/docs/authorizing-selling-partner-api-applications\n[rate-limits]: https://developer-docs.amazon.com/sp-api/docs/usage-plans-and-rate-limits\n[httprb]: https://github.com/httprb/http\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flineofflight%2Fpeddler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flineofflight%2Fpeddler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flineofflight%2Fpeddler/lists"}