Webhooks & Troubleshooting

Webhooks

Subscribe to eBay event notifications through EcartAPI's webhook system.

Method	Path	Description	API Reference
GET	`/api/v2/webhooks`	List all subscriptions	ref
GET	`/api/v2/webhooks/{id}`	Get a single subscription	ref
POST	`/api/v2/webhooks`	Create a subscription	ref
DELETE	`/api/v2/webhooks/{id}`	Delete a subscription	ref

Available events

Currently only one event type is supported:

`resource`	`action`	Description
`orders`	`create`	Triggered when a new order is created in eBay

Request body

Field	Required	Description
`resource`	Yes	The resource to subscribe to. Use `"orders"`.
`action`	Yes	The action to subscribe to. Use `"create"`.
`url`	Yes	Your destination URL where eBay will send the notification payload.

POST /api/v2/webhooks
{
  "webhook": {
    "resource": "orders",
    "action": "create",
    "url": "https://webhook.site/becaf99a-561a-4466-8a84-80290db3f1a2"
  }
}

Authentication and token management

EcartAPI handles OAuth token refresh automatically. When a request fails with 401, EcartAPI transparently refreshes the access token using the stored refresh token and retries the call. You do not need to implement token refresh in your application.

Warning — one store per app: If you connect the same eBay store to two different EcartAPI apps, each new connection invalidates the previous refresh token. The first app will stop working with 401 errors. A single eBay store should only be connected to one EcartAPI app at a time.

Common errors and solutions

Error	Likely cause	Solution
`errorId: 25604` — "SKU not found"	Product not in Inventory API	Verify with `GET /api/v2/products/{sku}`. If `404`, the product is not in the Inventory API — migrate it or create it fresh.
`errorId: 25705` — "Inventory Item Group not found"	Policies/locations for the wrong marketplace	Use the same `marketplaceId` throughout. Create policies and locations specifically for the target marketplace.
`errorId: 25718` — Invalid format	Wrong `marketplaceId` format	Use `EBAY_US` with an underscore, not `EBAY-US` with a hyphen.
`errorId: 32300` — "Invalid shipment tracking number or carrier"	Invalid carrier code or malformed tracking number	Use `GET /api/v2/services/carriers?ecommerce=true` to get valid carrier codes. → ref
`404` on `GET /api/v2/products/{sku}`	Product exists only as a legacy listing	Migrate the listing first via `POST /api/v2/products/listings/migrate`. → ref
Price unchanged after `PUT /api/v2/products/{sku}`	Price cannot be updated at inventory level	Update price at offer level via `PUT /api/v1/listings/{offerId}`. → ref
`401` after connecting a second app	Same eBay store connected to two apps	Reconnect the store to the intended app. One eBay store per EcartAPI app.
`"This listing is already migrated"`	eBay only allows migration once	Migration is irreversible. Add missing variants manually — see Products & Variants → Recovery: when a variant was missed.