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

# eBay Account API

Jentic publishes the only available OpenAPI specification for eBay Account API, keeping it validated and agent-ready. The Account API lets eBay sellers configure the operational policies that drive every listing - fulfillment policies, payment policies, return policies, and seller-defined custom policies. It also exposes endpoints for opting into and out of programs (such as the eBay Payments program), retrieving sales tax tables and rate tables, checking advertising eligibility, and reading KYC status. Authentication is OAuth 2.0 with the seller-account scope.

## For AI agents

Configure eBay seller policies (fulfillment, payment, return, custom) and program opt-ins, plus read advertising eligibility and KYC status, all from one structured 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 a seller's listings
- Manage payment policies including immediate-payment requirements and accepted methods
- Define and update return policies covering return windows, return shipping, and refund methods
- Author seller-defined custom policies (PRODUCT_COMPLIANCE, TAKE_BACK) and attach them to listings
- Opt the seller into or out of eBay programs, including the eBay Payments program
- Retrieve advertising eligibility, KYC status, privileges, and rate tables for the seller account

## Use cases

### Bulk policy provisioning for new sellers

Onboarding tools for new eBay sellers can create the full set of business policies - payment, fulfillment, and return - in one batch by calling POST /payment_policy, POST /fulfillment_policy/, and POST /return_policy. This produces a consistent listing template across thousands of items and lets the seller go live in minutes rather than configuring each policy manually in Seller Hub.

Example prompt: Call POST /payment_policy, POST /fulfillment_policy/, and POST /return_policy with the seller's standard configuration and store each returned policy_id for use on listings

### Marketplace compliance via custom policies

Sellers shipping into regulated EU marketplaces can author seller-defined custom policies of type PRODUCT_COMPLIANCE and TAKE_BACK using POST /custom_policy and attach them to listings. The Account API exposes the create/update/get/delete cycle for custom policies so a compliance pipeline can keep policy text in sync with regulatory updates.

Example prompt: Call POST /custom_policy with policyType TAKE_BACK and the localised policy body, then PUT /custom_policy/{custom_policy_id} when regulatory text changes

### Program opt-in for eBay Payments

Sellers migrating to the eBay Payments program can call GET /payments_program/{marketplace_id}/{payments_program_type} to read their current state and POST /program/opt_in to enroll. The onboarding endpoint at /payments_program/{marketplace_id}/{payments_program_type}/onboarding returns the URL the seller must complete to activate payouts. This automates a workflow that otherwise requires manual seller-hub navigation.

Example prompt: Call GET /payments_program/{marketplace_id}/EBAY_PAYMENTS, then POST /program/opt_in if not enrolled, and surface the onboarding URL from /payments_program/{marketplace_id}/EBAY_PAYMENTS/onboarding

### Agent-driven policy update via Jentic

An AI agent helping a seller respond to a policy change (e.g., extending the return window) can search Jentic for the eBay return-policy update operation, load its schema, and execute the update across every return policy on the account. Jentic stores the OAuth credentials in the vault, so the agent updates production policies without ever holding the raw access token.

Example prompt: Search Jentic for 'update an ebay return policy', list all return policies via GET /return_policy, then call PUT /return_policy/{return_policy_id} for each with the new return window

## Key endpoints

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

## Key resources

- **fulfillment_policy** — Create, list, update, and delete shipping/fulfillment policies
- **payment_policy** — Manage payment policies governing accepted methods and immediate-payment behaviour
- **return_policy** — Manage return policies including return windows and refund methods
- **custom_policy** — Author seller-defined policies for product compliance and take-back
- **program** — Opt the seller into or out of eBay programs and list opted-in programs
- **payments_program** — Read enrollment state and onboarding URL for the eBay Payments program

## Why Jentic

- **Setup:** Wiring the eBay Account API by hand means running its OAuth2 flow and coding your own calls to the fulfillment, return, and payment policy endpoints. Through Jentic you install once, import the eBay Account API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** eBay 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 fulfillment policies or KYC status, 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 fulfillment policy' or 'check advertising eligibility', and Jentic returns the matching eBay Account operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **eBay Sell Account API** — Sell Account is the same surface under the sell- namespace; account-api is the legacy slug
- **eBay Compliance API** — Compliance API surfaces listing violations that policy changes via Account API often resolve
- **eBay Sell Analytics API** — Sell Analytics reports performance trends; Account API is where the policies that influence those trends are configured
- **eBay Sell Fulfillment API** — Sell Fulfillment processes orders; Account API supplies the fulfillment policies that govern shipping options on those orders

## FAQ

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

eBay does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call eBay 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 eBay Account API use?

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

### Can I create a fulfillment policy with the eBay Account API?

Yes. POST /fulfillment_policy/ accepts a fulfillment policy body (handling time, shipping options, marketplace ID) and returns a fulfillmentPolicyId. You can later attach the policy to listings via the Inventory API or update it via PUT /fulfillment_policy/{fulfillmentPolicyId}.

### How do I look up a payment policy by name through Jentic?

Install the SDK with `pip install jentic`, then search Jentic for `find an ebay payment policy by name`. Load the schema for GET /payment_policy/get_by_policy_name, populate marketplace_id and name, and execute. Jentic returns the matching policy object with its policy_id.

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

Account API calls fall under eBay's standard application call limits - typically 5,000 calls per day per application key for production traffic, with per-second burst limits. Check your eBay Developer Program dashboard for the exact ceiling on your keyset.

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

Yes. Call POST /program/opt_in with the relevant program type, then read GET /payments_program/{marketplace_id}/{payments_program_type} to confirm enrollment state. The onboarding URL returned by /payments_program/{marketplace_id}/{payments_program_type}/onboarding completes any seller-side steps (e.g., bank verification) that require human action.

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

Yes. Because you self-host Jentic One, your own rules decide which eBay Account operations the agent may call, so you can grant read-only access to endpoints like GET /fulfillment_policy or GET /kyc while leaving policy creation such as POST /fulfillment_policy/ and POST /custom_policy out of the allowed set. This matters here because eBay carries policy targets in the request body rather than as ids in the URL path, so scoping is enforced at the operation level rather than by path pattern. Your stored eBay credentials are injected only for the operations you have explicitly granted, and every operation the agent can reach is your deliberate choice.