canonical: https://jentic.com/apis/api.ebay.com/ebay-sell-account-api

# eBay Sell Account API

Jentic publishes the only available OpenAPI specification for eBay Sell Account API, keeping it validated and agent-ready. The Sell Account API is the modern sell- namespace surface for configuring eBay seller policies - fulfillment, payment, return, and seller-defined custom policies - together with program opt-in/opt-out, KYC status, advertising eligibility, and rate tables. It is the canonical surface for any tool that creates or maintains the operational policies underpinning eBay listings. Authentication is OAuth 2.0 with the sell.account scope.

## For AI agents

Configure eBay seller policies (fulfillment, payment, return, custom), program opt-ins, and account settings via the canonical sell- namespace surface.

## Scope

Does not handle order processing, listing creation, or financial settlement - use for configuring eBay seller policies, programs, and account settings only.

## Capabilities

- Create, update, and delete fulfillment policies that govern shipping options on listings
- Manage payment policies covering accepted methods and immediate-payment requirements
- Author and update return policies with configurable return windows and refund methods
- Define seller custom policies for product compliance and take-back obligations
- Opt the seller into or out of eBay programs and read program enrollment state
- Read advertising eligibility, KYC status, privileges, and rate tables for the account

## Use cases

### Policy-as-code for eBay sellers

Engineering teams running eBay storefronts can manage every business policy as code by calling POST /fulfillment_policy/, POST /payment_policy, and POST /return_policy from CI. Subsequent updates flow through PUT endpoints keyed by policy_id. This replaces manual Seller Hub edits with reviewable, version-controlled changes.

Example prompt: Read policy definitions from version control and call POST or PUT on the matching /fulfillment_policy, /payment_policy, and /return_policy endpoint based on whether the policy_id already exists

### EU compliance via custom policies

Sellers exposed to EU GPSR or take-back regulations can author seller-defined custom policies via POST /custom_policy with policyType TAKE_BACK or PRODUCT_COMPLIANCE, then update the body via PUT /custom_policy/{custom_policy_id} as legal text changes. The Sell Account surface covers the full lifecycle of these policies.

Example prompt: Call POST /custom_policy with policyType TAKE_BACK and the localised body, store the returned customPolicyId, and PUT updates as text changes

### Onboarding sellers to eBay Payments

Workflow tools for new eBay sellers can call POST /program/opt_in and read GET /payments_program/{marketplace_id}/{payments_program_type}/onboarding to surface the activation URL the seller must complete. The opt-in flow is required before the seller can receive payouts via eBay's managed payments.

Example prompt: Call POST /program/opt_in for EBAY_PAYMENTS, then return the onboarding URL from GET /payments_program/{marketplace_id}/EBAY_PAYMENTS/onboarding

### Agent-driven policy update via Jentic

An AI agent receiving a new shipping carrier directive can search Jentic for the eBay fulfillment-policy update operation, list the seller's policies, and PUT the new carrier configuration on every matching policy. Jentic handles the OAuth refresh under the hood so the agent works only with high-level intents.

Example prompt: Search Jentic for 'update an ebay fulfillment policy', list policies via GET /fulfillment_policy, then PUT each /fulfillment_policy/{fulfillmentPolicyId} with the new carrier

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /fulfillment_policy/ | Create a fulfillment policy |
| POST | /payment_policy | Create a payment policy |
| POST | /return_policy | Create a return policy |
| POST | /custom_policy | Create a seller-defined custom policy |
| POST | /program/opt_in | Opt into a program |
| GET | /kyc | Read seller KYC status |
| GET | /advertising_eligibility | Check eligibility for promoted listings |

## Key resources

- **fulfillment_policy** — CRUD over shipping/fulfillment policies
- **payment_policy** — CRUD over payment policies
- **return_policy** — CRUD over return policies
- **custom_policy** — Author and update seller-defined custom policies
- **program** — Opt the seller into or out of eBay programs
- **payments_program** — Read enrollment state and onboarding URL for managed payments

## Why Jentic

- **Setup:** Wiring the eBay Sell Account API by hand means running its OAuth2 flow and coding your own calls to the fulfillment, payment, and return policy endpoints. Through Jentic you install once, import the eBay Sell Account API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** eBay Sell Account policy targets travel in the request body rather than as ids in the URL path, so limit the agent to the operations it needs, such as reading KYC or advertising eligibility, and leave policy creation out of the allowed set. Every operation you grant is your explicit choice.
- **Credential handling:** Your eBay token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a payment policy' or 'opt into a seller program', and Jentic returns the matching eBay Sell Account operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **eBay Account API** — Same surface under the legacy slug; same 36 endpoints
- **eBay Sell Compliance API** — Sell Compliance reports listing violations that policy updates here often resolve
- **eBay Sell Analytics API** — Sell Analytics measures performance trends; Sell Account is where the policies that influence those trends are configured
- **eBay Sell Fulfillment API** — Sell Fulfillment ships orders against the fulfillment policies defined here

## FAQ

### Why is there no official OpenAPI spec for eBay Sell Account API?

eBay does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call eBay Sell Account API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Sell Account API use?

OAuth 2.0 with the sell.account scope (https://api.ebay.com/oauth/api_scope/sell.account), obtained via eBay's user-token flow. Through Jentic, the OAuth client and refresh token are stored encrypted in your Jentic One instance and short-lived access tokens are minted per call.

### How is sell-account different from the legacy account-api slug?

The two surfaces share the same 36 endpoints and contract - Sell Account is the modern slug under eBay's sell- namespace. New integrations should target sell-account; account-api is retained for tooling that imported the original publication path.

### Can I create a fulfillment policy through Jentic?

Yes. Install with `pip install jentic`, search Jentic for `create an ebay fulfillment policy`, load the schema for POST /fulfillment_policy/, populate handling time and shipping options, and execute. The response returns a fulfillmentPolicyId you can attach to listings.

### What are the rate limits for the Sell Account API?

Sell Account calls fall under eBay's standard application call ceiling - typically 5,000 calls per day per application key in production with per-second burst caps. Verify the exact limit on your keyset in the eBay Developer Program dashboard.

### Can I opt a seller into the eBay Payments program?

Yes. POST /program/opt_in enrolls the seller; GET /payments_program/{marketplace_id}/{payments_program_type} confirms the enrollment state; and /payments_program/{marketplace_id}/{payments_program_type}/onboarding returns any seller-side activation URL still required.

### Can I limit what my agent is allowed to do with the eBay Sell Account API?

Yes. Because you run Jentic One yourself, your own rules decide which eBay Sell Account operations and credentials the agent may use. You can grant only read operations such as GET /kyc or GET /advertising_eligibility and leave the policy-writing endpoints like POST /fulfillment_policy, POST /payment_policy, and POST /custom_policy out of the allowed set. Since policy targets travel in the request body rather than as ids in the URL path, every operation the agent can call is your explicit choice.