eBay Fulfillment API

The eBay Fulfillment API, part of eBay's Sell APIs, lets sellers manage the post-checkout order lifecycle on the marketplace. Sellers retrieve and track orders, create shipping fulfillments with carrier and tracking info, issue refunds, and handle buyer payment disputes end-to-end. It's essential for automating order operations and integrating eBay order data into logistics systems.

Power end-to-end data operations for your eBay Fulfillment API API with Nexla. Our bi-directional eBay Fulfillment API connector is purpose-built for eBay Fulfillment API, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to eBay Fulfillment API or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your eBay Fulfillment API workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

The eBay Fulfillment API uses OAuth 2.0 (3-legged authorization code flow), which requires you to register an application in the eBay Developer Program and obtain an App ID (Client ID) and Cert ID (Client Secret). These credentials identify your registered application and authorize it to act on behalf of an eBay seller account.

Register for the eBay Developer Program

1. Go to https://developer.ebay.com and sign in with your eBay account, or create a new eBay account if you do not already have one.

2. Once signed in, navigate to Hi, [your name] in the top navigation and select Account to access the Developer Program account settings.

Create an Application Keyset

3. Navigate to Application Keys in the developer portal (or go directly to https://developer.ebay.com/my/keys).

4. Click Create a keyset under the Production environment (use Sandbox for testing).

5. Enter a name for your application in the Application Title field, then click Continue.

6. Confirm your primary contact information when prompted, then click Submit.

7. eBay will generate three key values for your application:

   • App ID (Client ID): Uniquely identifies your registered application. This value is used as the Client ID in the Nexla credential.

   • Dev ID: Uniquely identifies your developer account profile. This value is not required for Nexla configuration.

   • Cert ID (Client Secret): Acts as the client secret for token requests. Keep this value confidential—do not share or expose it publicly.

   Store your App ID and Cert ID in a secure location immediately after creation. The Cert ID is sensitive and should be treated like a password. For production use, always create a Production keyset; use the Sandbox keyset only for development and testing.

8. Before you can use your Production keyset, eBay requires you to subscribe to or opt out of eBay marketplace account deletion/closure notifications. Follow the prompts on the Application Keys page to complete this step.

Configure OAuth Redirect URI

9. In the eBay Developer Portal, navigate to Get a Token from eBay via Your Application (or the OAuth settings section for your keyset).

10. Add Nexla's OAuth redirect/callback URI as an allowed RuName (eBay Redirect URL name). eBay uses RuNames to map redirect URIs to your application. Consult your Nexla instance configuration or contact Nexla support for the exact redirect URI to register.

Confirm Required OAuth Scope

11. The eBay Fulfillment API requires the https://api.ebay.com/oauth/api_scope/sell.fulfillment OAuth scope to access order and shipping fulfillment data. This scope is pre-configured as the default in the Nexla eBay Fulfillment API credential. Confirm that your application keyset includes this scope by reviewing the scopes assigned to your keyset in the Developer Portal.

    For complete details on obtaining eBay OAuth credentials, see the Getting your OAuth credentials guide in the eBay Developers Program documentation.

Authenticate

Credentials required

3-legged OAuth2 authorization for eBay Fulfillment API. User grants application access to manage orders and fulfillment on their behalf.

Field	Required	Secret	Description
Authorization URL	No	No	The URL endpoint where users authenticate and authorize access
Client ID (App ID)	Yes	Yes	The eBay App ID (also called client_id) for the registered keyset.
Access Scope	No	No	Space-separated list of OAuth scopes. Fulfillment API requires https://api.ebay.com/oauth/api_scope/sell.fulfillment
Token URL	No	No	The URL endpoint where authorization codes are exchanged for access tokens
Client Secret (Cert ID)	Yes	Yes	The eBay Cert ID (also called client_secret) used to authenticate token requests.
Base URL	Yes	No	eBay Fulfillment API base URL (production or sandbox environment) Allowed values: Production; Sandbox

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

The eBay Fulfillment API credential uses a 3-legged OAuth 2.0 flow, which means an eBay seller must interactively grant your application access to manage orders and fulfillment on their behalf. After granting access, eBay issues access tokens that Nexla uses for all API calls.

3. In the Authorization URL field, confirm or enter the eBay OAuth authorization endpoint. The default value is https://auth.ebay.com/oauth2/authorize and should not need to be changed for Production use. For Sandbox, use https://auth.sandbox.ebay.com/oauth2/authorize.

4. Enter your application's App ID (also referred to as Client ID) in the Client ID (App ID) field. This is the App ID generated when you created your application keyset in the eBay Developer Portal.

5. In the Access Scope field, enter the space-separated list of OAuth scopes that this credential will request. The default value is https://api.ebay.com/oauth/api_scope/sell.fulfillment, which grants access to view and manage order fulfillments. Additional scopes can be added as needed:

   • https://api.ebay.com/oauth/api_scope/sell.fulfillment — View and manage order fulfillments (required for the Fulfillment API)

   • https://api.ebay.com/oauth/api_scope/sell.finances — View and manage payment and order financial information (required for issuing refunds)

   • https://api.ebay.com/oauth/api_scope/sell.payment.dispute — View and manage payment disputes and related details

6. In the Token URL field, confirm or enter the eBay token exchange endpoint. The default value is https://api.ebay.com/identity/v1/oauth2/token and is used to exchange authorization codes for access tokens.

7. Enter your application's Cert ID (also referred to as Client Secret) in the Client Secret (Cert ID) field. This is the Cert ID generated alongside your App ID in the eBay Developer Portal. This value is stored securely and used to authenticate token requests.

8. In the Base URL field, select the environment for this credential:

   • Production: https://api.ebay.com/sell/fulfillment/v1 — Use this for live eBay seller accounts.

   • Sandbox: https://apiz.ebay.com/sell/fulfillment/v1 — Use this for testing and development.

   The Sandbox environment is a replica of the Production environment that allows developers to test integrations without affecting real orders or seller accounts. Additional information about eBay's OAuth token flows is available in the Get OAuth access tokens documentation.

9. After all fields are configured, Nexla will redirect you to eBay's authorization page, where the eBay seller whose account will be accessed must sign in and grant consent to the requested scopes.

10. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the eBay Fulfillment API connector tile, then select the credential that will be used to connect to the eBay Fulfillment API instance, and click Next; or, create a new eBay Fulfillment API credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common eBay Fulfillment API endpoints. Each template is designed specifically for the corresponding eBay Fulfillment API endpoint, making data source setup easy and efficient. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

Get Order

Retrieves the complete details of a single eBay order by its order ID. Use this endpoint when you need full details for a specific known order, such as buyer information, line items, pricing, payment status, and fulfillment details.

• Enter the unique order identifier in the Orderid field. eBay order IDs are alphanumeric strings that uniquely identify each transaction. You can find order IDs in the eBay Seller Hub, in prior order list responses, or in buyer notification emails.

• Optionally, enter a comma-separated list of field group names in the Field Groups field to control which sections of the order data are included in the response. Supported values include:

  • TAX_BREAKDOWN — Includes a detailed breakdown of taxes applied at the line-item and order level.

  If left blank, the default set of order fields is returned.

This endpoint returns data for a single order and does not paginate. For retrieving multiple orders at once or filtering orders by date or status, use the Get Orders endpoint instead. Additional details are available in the getOrder API reference.

Get Orders

Retrieves a paginated list of eBay orders with optional filtering and field selection. Use this endpoint to pull batches of orders for reporting, analytics, or synchronization with downstream systems. It supports filtering by date range, order status, and specific order IDs.

• Optionally, enter a comma-separated list of field group names in the Field Groups field to control which additional data sections are included in each order record. Supported values include:

  • TAX_BREAKDOWN — Includes a detailed breakdown of taxes applied at the line-item and order level.

  If left blank, the standard set of order fields is returned for each order.

• Optionally, enter one or more comma-separated filter criteria in the Filter field to narrow the list of orders returned. Common filter expressions supported by the eBay Fulfillment API include:

  • creationdate — Filter orders by creation date range, e.g., creationdate:[2024-01-01T00:00:00.000Z..2024-03-31T23:59:59.999Z]
  • lastmodifieddate — Filter orders by last modification date range.
  • orderfulfillmentstatus — Filter by fulfillment status, e.g., orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS}

  Filter criteria must follow eBay's filter syntax. If left blank, all available orders are returned.

• Optionally, enter a comma-separated list of specific eBay order IDs in the Order IDs field to retrieve only those orders. This is useful when synchronizing a known set of orders rather than querying by date or status.

This endpoint uses offset-based pagination and automatically fetches additional pages until all matching orders have been retrieved. The eBay Fulfillment API returns a maximum of 200 orders per page. Additional details are available in the getOrders API reference.

Get Shipping Fulfillments

Retrieves all shipping fulfillments associated with a specific eBay order. Use this endpoint to get the full list of shipments, carrier details, and tracking numbers for a given order.

• Enter the eBay order identifier in the Order ID field. This is the same order ID used in other order endpoints and identifies which order's fulfillments should be retrieved.

Each fulfillment record includes the carrier used, the tracking number, the shipment date, and the line items included in that shipment. To retrieve details for a single specific fulfillment, use the Get Shipping Fulfillment endpoint instead. Additional details are available in the getShippingFulfillments API reference.

Get Shipping Fulfillment

Retrieves the details of a specific shipping fulfillment within an eBay order, identified by both the order ID and the fulfillment ID. Use this endpoint when you need detailed information about a single shipment, including carrier, tracking number, shipment date, and included line items.

• Enter the eBay order identifier in the Orderid field to specify which order the fulfillment belongs to.
• Enter the unique identifier of the specific shipping fulfillment in the Fulfillmentid field. Fulfillment IDs can be obtained by first calling the Get Shipping Fulfillments endpoint for the relevant order.

Both the order ID and the fulfillment ID are required for this endpoint. Additional details are available in the getShippingFulfillment API reference.

Get Payment Dispute Details

Retrieves complete details about a specific payment dispute, including the dispute reason, status, buyer information, order details, and any evidence or activity associated with the dispute. Use this endpoint to monitor the status and details of an active or resolved dispute.

• Enter the unique identifier of the payment dispute in the Payment Dispute Id field. Payment dispute IDs are assigned by eBay when a buyer opens a dispute through their payment provider (such as PayPal or a credit card issuer) and can be found in eBay's dispute notifications or by using the Search Payment Disputes endpoint.

Payment disputes are buyer-initiated disputes opened with their payment provider, not eBay's own resolution center cases. Additional details are available in the getPaymentDispute API reference.

Get Payment Dispute Evidence File

Retrieves the binary content of a specific evidence file that has been uploaded in connection with a payment dispute. Use this endpoint to retrieve supporting documentation files (such as shipping labels, tracking records, or item photos) that were submitted as dispute evidence.

• Enter the unique identifier of the payment dispute in the Payment Dispute Id field.
• Enter the unique identifier of the evidence submission in the Evidence ID field. Evidence IDs are returned when evidence is added to a dispute and can also be found in the dispute details from the Get Payment Dispute Details endpoint.
• Enter the unique identifier of the specific file to retrieve in the File ID field. File IDs are associated with individual uploaded files within an evidence submission.

This endpoint is available in the v2 API path. All three parameters (Payment Dispute ID, Evidence ID, and File ID) are needed to uniquely identify the file to retrieve. Additional details are available in the fetchEvidenceContent API reference.

Get Payment Dispute Activity

Retrieves the full activity history and timeline for a specific payment dispute, showing a chronological log of all actions taken by the seller, buyer, and eBay throughout the dispute lifecycle. Use this endpoint to audit dispute handling or track progress toward resolution.

• Enter the unique identifier of the payment dispute in the Payment Dispute Id field. The activity log returned includes timestamped entries for each action, such as when the dispute was opened, when evidence was submitted, and when decisions were made.

Additional details are available in the getActivities API reference.

Search Payment Disputes

Searches for payment disputes using a combination of filters including order ID, buyer username, dispute status, and date range. Use this endpoint to retrieve a list of disputes matching your criteria for batch processing, reporting, or monitoring open disputes.

• Optionally, enter a specific eBay order ID in the Order ID field to retrieve disputes associated with that order.
• Optionally, enter the buyer's eBay username in the Buyer Username field to filter disputes initiated by that buyer.
• Optionally, enter an ISO 8601 date-time string in the Open Date From field to retrieve only disputes opened on or after that date (e.g., 2024-01-01T00:00:00.000Z).
• Optionally, enter an ISO 8601 date-time string in the Open Date To field to retrieve only disputes opened on or before that date.

• Optionally, enter a dispute status value in the Payment Dispute Status field to filter results by status. Supported values include:

  • OPEN — Disputes that are currently open and awaiting action.
  • CLOSED — Disputes that have been resolved and closed.
  • ACTION_NEEDED — Disputes requiring immediate seller action.
  • APPEALABLE — Disputes where the seller's decision can be appealed.

This endpoint uses offset-based pagination, automatically retrieving additional pages until all matching disputes have been returned. Additional details are available in the getPaymentDisputeSummaries API reference.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

eBay Fulfillment API data sources can also be manually configured to ingest data from any valid eBay Fulfillment API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

eBay Fulfillment API endpoints follow the base URL pattern https://api.ebay.com/sell/fulfillment/v1/ for Production (or https://apiz.ebay.com/sell/fulfillment/v1/ for Sandbox), followed by the resource path—for example, https://api.ebay.com/sell/fulfillment/v1/order to retrieve all orders. Date/time macros are particularly useful for filter parameters such as creationdate or lastmodifieddate, and lookup-based macros are useful for referencing order IDs, dispute IDs, or other identifiers pulled from another Nexla data source.

Set Path to Data in Response to $.orders[*] for the getOrders endpoint, $.fulfillments[*] for shipping fulfillments, or $.paymentDisputeSummaries[*] for dispute summaries; single-object endpoints such as Get Order do not require a path. The total and limit fields returned alongside the orders array can be preserved as metadata on each record via Path to Metadata in Response. You do not need to include the eBay Fulfillment API's OAuth authorization header in Request Headers—this is handled automatically based on your credential configuration—but you may need to add the X-EBAY-C-MARKETPLACE-ID header for marketplace-specific requests (e.g., X-EBAY-C-MARKETPLACE-ID:EBAY_US).

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new eBay Fulfillment API data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination

Click the + icon on the Nexset that will be sent to the eBay Fulfillment API destination, and select the Send to Destination option from the menu. Select the eBay Fulfillment API connector from the list of available destination connectors, then select the credential that will be used to connect to the eBay Fulfillment API organization, and click Next; or, create a new eBay Fulfillment API credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common eBay Fulfillment API endpoints. Each template is designed specifically for the corresponding eBay Fulfillment API endpoint, making destination setup easy and efficient. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Issue Refund

Issues a full or partial refund for a specific eBay order on behalf of the seller. Use this endpoint to programmatically process order cancellations, return-related refunds, or goodwill adjustments. Refunds can be applied at the order level or targeted to individual line items within an order.

• Enter the eBay order identifier in the Order Id field. This is the unique ID of the order for which a refund is being issued. The refund request body sent from the Nexset should include the refund details such as the reason code, comment, and optionally a list of line items with their refund amounts.

Issuing a refund requires the https://api.ebay.com/oauth/api_scope/sell.finances OAuth scope in addition to the fulfillment scope. Ensure this scope is included in your eBay Fulfillment API credential. Additional details are available in the issueRefund API reference.

Create Shipping Fulfillment

Creates a new shipping fulfillment record for an eBay order, associating a shipment with specific line items and providing carrier and tracking information. Use this endpoint to programmatically mark orders as shipped and notify eBay of tracking details—this triggers buyer notifications and updates the order's fulfillment status.

• Enter the eBay order identifier in the Orderid field. The request body sent from the Nexset should include the following shipment details:

  • lineItems — An array of line item objects specifying which items in the order are included in this shipment, along with quantities.
  • shippingCarrierCode — The carrier code for the shipping provider (e.g., USPS, UPS, FEDEX). eBay maintains a list of supported carrier codes.
  • trackingNumber — The tracking number assigned to the shipment by the carrier.
  • shippedDate — The date and time the package was shipped, in ISO 8601 format.

eBay requires that at least one line item be included in each shipping fulfillment. Providing accurate carrier codes and tracking numbers ensures buyers receive correct tracking information and eBay records the fulfillment status accurately. Additional details are available in the createShippingFulfillment API reference.

Contest Payment Dispute

Contests a buyer-initiated payment dispute by submitting a seller response that includes a note, return address, and optional revision details. Use this endpoint when a seller wants to formally dispute a buyer's chargeback or payment dispute claim with supporting context.

• Enter the unique identifier of the payment dispute in the Payment Dispute ID field. The request body sent from the Nexset should include:

  • note — A seller-provided explanation or response to the dispute.
  • returnAddress — The seller's return address, required if the buyer is expected to return the item.
  • revision — An integer tracking value that must match the current revision number of the dispute (obtained from the dispute details) to prevent conflicting updates.

Only disputes in an actionable state can be contested. Review the dispute status using the Get Payment Dispute Details source endpoint before contesting. Additional details are available in the contestPaymentDispute API reference.

Accept Payment Dispute

Accepts a buyer-initiated payment dispute, indicating the seller agrees to the buyer's claim. Use this endpoint when the seller determines that accepting the dispute is the appropriate resolution, such as for valid return requests or acknowledged order issues.

• Enter the unique identifier of the payment dispute in the Payment Dispute ID field. The request body sent from the Nexset may include:

  • returnAddress — The seller's return address, required if the resolution involves a buyer return.
  • revision — An integer tracking value that must match the current revision number of the dispute to prevent conflicting updates.

Accepting a dispute typically results in a refund being issued to the buyer. Ensure the dispute is in an actionable state before accepting. Additional details are available in the acceptPaymentDispute API reference.

Upload an Evidence File

Uploads a binary evidence file to support a seller's case in a payment dispute. Use this endpoint to programmatically attach supporting documentation—such as shipping labels, tracking screenshots, item photos, or correspondence—as part of contesting a dispute.

• Enter the unique identifier of the payment dispute in the Payment Dispute ID field. The uploaded file content should be provided in the request body from the Nexset. eBay accepts image file formats (JPG, JPEG, PNG, GIF, TIFF, BMP) with a maximum file size of 1.5 MB per file.

Files uploaded with this endpoint are not automatically linked to a dispute evidence submission—use the Add an Evidence File endpoint after uploading to associate the uploaded file with an evidence entry. Additional details are available in the uploadEvidenceFile API reference.

Add an Evidence File

Adds a new evidence submission to a payment dispute, associating one or more previously uploaded files with an evidence type and specific line items. Use this endpoint after uploading file(s) with the Upload an Evidence File endpoint to formally submit them as dispute evidence.

• Enter the unique identifier of the payment dispute in the Payment Dispute ID field. The request body sent from the Nexset should include:

  • evidenceType — The type of evidence being submitted, such as PROOF_OF_SHIPPING, PROOF_OF_AUTHENTICITY, PROOF_OF_DELIVERY, or OTHER.
  • files — An array of file ID objects referencing the files uploaded via the Upload an Evidence File endpoint.
  • lineItems — An array of line item references indicating which order items the evidence relates to.

Evidence must be submitted while the dispute is still in a contestable state. Additional details are available in the addEvidence API reference.

Update evidence

Updates an existing evidence submission on a payment dispute with new files, a revised evidence type, or updated line item associations. Use this endpoint to modify previously submitted evidence before the dispute deadline.

• Enter the unique identifier of the payment dispute in the Payment Dispute ID field. The request body sent from the Nexset should include:

  • evidenceId — The unique identifier of the existing evidence submission to update.
  • evidenceType — The updated type of evidence being submitted.
  • files — An updated array of file ID objects to associate with this evidence submission.
  • lineItems — An updated array of line item references for the evidence.

The evidence ID can be obtained from the dispute details returned by the Get Payment Dispute Details source endpoint. Additional details are available in the updateEvidence API reference.

Manual configuration

eBay Fulfillment API destinations can also be manually configured to send data to any valid eBay Fulfillment API endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

eBay Fulfillment API write operations use POST for creating new resources (such as shipping fulfillments and dispute actions), and accept application/json for all write operations. Endpoints follow the base URL pattern https://api.ebay.com/sell/fulfillment/v1/ followed by the resource path—for example, to issue a refund for a specific order, the URL is https://api.ebay.com/sell/fulfillment/v1/order/{orderId}/issue_refund. Replace path parameters such as the order ID or payment dispute ID with the actual values for each record, or use Nexla's lookup-based macros to dynamically populate them from the Nexset data.

You do not need to include the eBay Fulfillment API's OAuth authorization header or the Content-Type: application/json header in Request Headers—these are automatically handled by Nexla based on your credential and data format configuration. You may add the X-EBAY-C-MARKETPLACE-ID header if marketplace-specific behavior is required (e.g., X-EBAY-C-MARKETPLACE-ID:EBAY_US).

Save & activate

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured eBay Fulfillment API endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to the eBay Fulfillment API until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.