canonical: https://jentic.com/apis/ebay.com/sell-fulfillment

# Ebay Sell Fulfillment API

The eBay Sell Fulfillment API is where sellers complete the post-checkout half of the transaction - read placed orders, create shipping fulfillments with tracking numbers, issue refunds, and manage payment disputes including evidence upload, contest, and accept actions. The 15 endpoints split across two resources: /order for the order lifecycle and /payment_dispute for buyer-initiated disputes. All operations require a User access token in the seller's context.

## For AI agents

Process eBay orders post-checkout - read order detail, create shipping fulfillments with tracking, issue refunds, and manage buyer payment disputes. 15 endpoints, user-context only.

## Scope

Does not handle listing creation, payment processing, or buyer-side search - use for post-checkout order processing, shipping, refunds, and payment-dispute resolution only.

## Capabilities

- Read placed-order detail including buyer, line items, shipping address, and totals
- Create a shipping fulfillment with carrier and tracking number to mark an order as shipped
- Issue a refund (full or partial) for an order via POST /order/{order_id}/issue_refund
- Search payment disputes by status, date range, or order ID
- Contest, accept, or upload evidence for a buyer-initiated payment dispute
- Read a payment dispute's activity log and evidence files for audit trails
- Filter orders by status (UNSHIPPED, SHIPPED, COMPLETED) for fulfillment dashboards

## Use cases

### Shipping-tracking sync from a 3PL

When a 3PL warehouse ships an order, its system POSTs to /order/{orderId}/shipping_fulfillment with the carrier code, tracking number, and the line items included in that shipment. eBay then notifies the buyer with tracking and updates the order to SHIPPED. Multi-shipment orders are handled by issuing one shipping_fulfillment per package.

Example prompt: POST /order/{orderId}/shipping_fulfillment with carrierCode='USPS', trackingNumber='9400...', and the lineItems array shipped in this package

### Damage refund automation

Customer-service tools handle damage-claim refunds by calling /order/{order_id}/issue_refund with the agreed amount and a reasonCode (typically BUYER_RETURN). The endpoint accepts partial refunds, so the tool can reproduce a 'keep the item, refund 50%' agreement without an agent manually navigating eBay's web UI.

Example prompt: POST /order/{order_id}/issue_refund with amount={value:25.00,currency:'USD'} and reasonCode=BUYER_RETURN

### Payment dispute response workflow

When a buyer files a payment dispute, the seller's tool reads the dispute via GET /payment_dispute/{payment_dispute_id} plus its activity log and evidence files. If the seller has shipping evidence, the tool POSTs to /payment_dispute/{payment_dispute_id}/upload_evidence_file followed by /add_evidence and /contest. If the seller agrees with the buyer, /accept resolves the dispute in the buyer's favour without further action.

Example prompt: Get payment dispute 5004, upload the proof-of-delivery PDF via /upload_evidence_file, attach via /add_evidence, then call /contest with reason 'item delivered'

### Order dashboard for a multi-channel SaaS

Multi-channel seller dashboards poll GET /order with filter 'orderfulfillmentstatus:{NOT_STARTED}' to surface unshipped eBay orders alongside the seller's other marketplaces. Drilling into an order calls GET /order/{orderId} for full detail, including the buyer's shipping address and any charity attribution on the line items.

Example prompt: Call /order with filter='orderfulfillmentstatus:{NOT_STARTED}' and limit=50, then for each id call /order/{orderId}

### AI agent integration via Jentic

An AI agent that handles a seller's customer service searches Jentic for 'issue an eBay refund'. Jentic returns POST /order/{order_id}/issue_refund with its required schema. The agent loads the schema, executes the call with a User access token issued through Jentic's vault, and the refund posts to the buyer without the agent storing the seller's refresh token.

Example prompt: Use Jentic to search 'issue an eBay refund', load POST /order/{order_id}/issue_refund, and execute it with the order ID and refund amount

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /order | List orders, filterable by status, date, or buyer |
| GET | /order/{orderId} | Get full detail for one order |
| POST | /order/{orderId}/shipping_fulfillment | Create a shipping fulfillment record with tracking |
| POST | /order/{order_id}/issue_refund | Issue a full or partial refund |
| GET | /payment_dispute_summary | Search payment disputes by filter |
| GET | /payment_dispute/{payment_dispute_id} | Get full detail for one payment dispute |
| POST | /payment_dispute/{payment_dispute_id}/contest | Contest a payment dispute |
| POST | /payment_dispute/{payment_dispute_id}/upload_evidence_file | Upload an evidence file for a payment dispute |

## Key resources

- **order** — Read placed orders, create shipping fulfillments, issue refunds
- **shipping_fulfillment** — Per-package shipment records with carrier and tracking
- **payment_dispute** — Read, contest, accept, and submit evidence on buyer-initiated payment disputes

## Why Jentic

- **Setup:** Wiring the eBay Sell Fulfillment API by hand means implementing eBay's OAuth 2.0 authorization-code flow for a seller user token, refreshing it, and pointing requests at the api.ebay.com sell/fulfillment host across order, shipping, and dispute endpoints. Through Jentic you install once, import the Sell Fulfillment API from the API Directory, store the eBay OAuth credentials once, and your agent calls it.
- **Permission scoping:** Fulfillment operations put the resource id in the URL path, such as /order/{orderId} and /payment_dispute/{payment_dispute_id}, so a rule can pin your agent to one order or one dispute. You choose the operations it may call, so a shipping agent gets order reads and shipping_fulfillment while refunds and dispute contests are not included unless you add them.
- **Credential handling:** Your eBay OAuth seller credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'mark an eBay order shipped' or 'issue an eBay refund', and Jentic returns the matching /order or /payment_dispute 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 configures the fulfillment policy that Sell Fulfillment orders inherit.
- **eBay Sell Feed API** — Sell Feed is the bulk-export equivalent for orders; Sell Fulfillment is the per-order surface.
- **eBay Sell Analytics API** — Sell Analytics surfaces the customer-service metrics that Sell Fulfillment behaviour drives.

## FAQ

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

The Sell Fulfillment API uses OAuth 2.0 with the Authorization Code grant - every endpoint operates in the seller's context, so a User access token is required. Through Jentic, the seller's refresh token sits in your Jentic One instance and the agent receives a scoped access token for the sell.fulfillment scope only.

### Can I issue a partial refund through the Sell Fulfillment API?

Yes. POST /order/{order_id}/issue_refund with an amount object specifying the refund value and currency, plus a reasonCode (e.g., BUYER_RETURN). Pass less than the order total to issue a partial refund. The endpoint requires an explicit reason - there is no zero-context refund path.

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

Sell Fulfillment falls under the Sell APIs user-context daily quota issued per application-and-user pair. Call /user_rate_limit on the Developer Analytics API and inspect the sell.fulfillment entry to read the live remaining count for the authenticated seller.

### How do I mark an order shipped through Jentic?

Search Jentic for 'mark eBay order shipped with tracking', load POST /order/{orderId}/shipping_fulfillment, and execute it with carrierCode, trackingNumber, and the lineItems shipped. Install with pip install jentic. Get started with Jentic One, the self-hosted execution layer.

### Can I respond to payment disputes programmatically?

Yes. /payment_dispute exposes /contest, /accept, /upload_evidence_file, /add_evidence, and /update_evidence so a seller's tool can run the entire response workflow - pull the dispute, upload proof of delivery or refund, attach it as evidence, and contest - all without using the eBay web UI.

### How do I find unshipped orders only?

Call GET /order with filter='orderfulfillmentstatus:{NOT_STARTED}' to return orders that have no shipping fulfillment yet. Combine with creationdate filters to limit to recent windows for dashboard refresh jobs.

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

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, so you can grant a shipping agent only order reads and POST /order/{orderId}/shipping_fulfillment while leaving out issue_refund and payment-dispute actions like contest and accept unless you add them. Since the resource id sits in the URL path, such as /order/{orderId} and /payment_dispute/{payment_dispute_id}, you can also pin the agent to a single order or dispute. Your eBay OAuth seller credentials stay in your own instance and are injected only at execution time, never entering the agent's prompt or logs.