Developer notes
Technical reference for developers who customize Amazon Seller Connector (SP-API).
Add-on identity
Section titled “Add-on identity”| Item | Value |
|---|---|
| Add-on id | kv_amazon_sp |
| Function prefix | fn_kv_amazon_sp_ |
| Language variables | kv_amazon_sp.* |
| CSS scope | .kv-amazon-sp |
| PHP namespace | Tygh\Addons\KvAmazonSp |
| Preset | marketplace (generated by kv new --kind integration) |
Structure
Section titled “Structure”| Class | Role |
|---|---|
Client\BaseClient |
HTTP (cURL, TLS verification, timeouts), JSON, error mapping, masked logging |
Client\Api |
Amazon SP-API calls: Login with Amazon refresh token exchange (cached below its one hour expiry), x-amz-access-token + User-Agent on every call, regional and sandbox hosts, Sellers, Product Type Definitions, Listings Items 2021-08-01, Catalog Items 2022-04-01, Tokens (Restricted Data Token), Orders v2026-01-01 and v0, confirmShipment; marketplace table (id, region, currency, locale) |
Drivers\Amazon\Driver |
Implements Hub\DriverInterface: product types as categories, schema attributes, listings, price / quantity patches, order polling, shipment confirmation |
Drivers\Amazon\Mapper |
Pure translation (no HTTP): schema to attributes and values, hub listing to putListingsItem body, patch bodies, issues to errors, v2026 and v0 orders to the hub order shape |
Client |
Client per company, the connection test |
Accounts, Secret |
Credentials (test and live) sealed with AES-256-GCM; one account per store owner or per vendor |
Config, Access |
Settings, owner mode, who may see and manage what |
Queue, Jobs, JobException |
Job queue: back-off 5 min / 15 min / 1 h / 3 h / 12 h, per-job isolation, overlap lock; handlers in Jobs::handle(), recurring work in Jobs::schedule() |
Log |
Event log with masking, filters, CSV, retention |
Webhook |
Signature check and event ids; the controller kv_amazon_sp.webhook?c=<account> stores the event as a job |
Database tables
Section titled “Database tables”| Table | Purpose |
|---|---|
?:kv_amazon_sp_accounts |
Credentials per company (secrets sealed), last connection check, token cache |
?:kv_amazon_sp_log |
Log |
?:kv_amazon_sp_jobs |
Queue |
?:kv_amazon_sp_product_map, ?:kv_amazon_sp_order_map |
Product mapping and imported orders |
Hooks used
Section titled “Hooks used”update_product_post, delete_product_post (mark mapped products for the next push) and init_templater_post. Backend template hooks only add the license badge and styles.
Amazon specifics
Section titled “Amazon specifics”- The refresh token is kept in the account’s third sealed secret (the column the generic hub calls the webhook secret); the label on the Connection page is “Refresh token”. Amazon push notifications are not used, the hub polls.
- SKU on Amazon = the barcode of the product map. A numeric 8, 12, 13 or 14 digit barcode is also sent as
externally_assigned_product_identifier(ean, upc, gtin); any other value uses the product identifier exemption. - Listings:
putListingsItemaccepts a submission at once; the driver keeps the batch open and readsgetListingsItem(summaries, issues) until the listing exists; ERROR issues fail the product with Amazon’s text. - Price:
patchListingsItemreplace/attributes/purchasable_offer; quantity: merge/attributes/fulfillment_availability(channel code DEFAULT). The product type of a SKU is remembered from the listing or read withgetListingsItem. - Orders: v2026-01-01
searchOrders(default) or v0getOrders+getOrderItemswith a Restricted Data Token (POST /tokens/2021-03-01/restrictedDataToken, dataElements buyerInfo and shippingAddress). v0 is deprecated since 2026-01-28 and removed on 2027-03-27. Orders without a delivery address are skipped with a log warning. - Throttling:
Client\Api::$pacespaces listing calls; a 429 answer is retryable and handled by the job queue.
Test the HTTP layer without the provider
Section titled “Test the HTTP layer without the provider”The base URL can be overridden for tests in config.local.php (development only):
$config['kv_amazon_sp_base_url'] = 'http://127.0.0.1:11934';node tests/mock-server/server.js 11934 starts a local stand-in of the provider API; node tests/e2e/e2e.mjs runs the HTTP end-to-end test against it; php tests/unit.php runs the unit tests.
Template overrides
Section titled “Template overrides”Admin templates live in design/backend/templates/addons/kv_amazon_sp/. Do not edit them in a store; they are replaced on update.