HemiKnowledge BaseHemiIntegrations
Table of Contents
Related Articles
Knowledge Base
Hemi System Administration Integrations Hemi PRD Library Hemi Content Stream General Information Custom additions Core Integrations & Marketplace Documentation Hemi Advanced Functionalities Data Management MP Tokens generation Hemi Technology Trainings Hemi Platform Integrations Release Notes
FAQs

Marketplaces / eBay / eBay Fulfillment API Technical Scope

eBay Fulfillment API Technical Scope

The purpose of this document is to give good understanding of the structure and functionality of the eBay Fulfillment API.

Fulfillment API

The outcome of a buyer's eBay checkout process is anorder. This API enables sellers to manage the completion of an order in accordance with the payment method and timing specified at checkout. The line items in the order are grouped into one or more packages. As the seller addresses, handles, and ships each package, the set of specifications for this process is known as afulfillment. Use the Fulfillment API to facilitate and monitor these activities from the order to completion. Sellers' status on eBay depend partly on their record of timely fulfillment.

Note:The Fulfillment API covers only the transactions that have completed the checkout process. This includes both paid purchases and purchases that do not require upfront payment (such as COD). However, the API does not cover pending payment purchases that require upfront payment before shipment.

The issueRefund and payment dispute methods can only be used by sellers opted in to eBay managed payments. eBay managed payments is currently only available to a limited number of US and German sellers, but this program is scheduled to become available to more sellers throughout 2019 and beyond.

Technical overview

The checkout process produces an order and generates its order identifier, which serves as the starting point for the Fulfillment API.

Order Statuses

eBay will be using 4 different status which we will have to handle: CancelStatus :

CANCELED

This enumeration value indicates that the order has been cancelled.

IN_PROGRESS

This enumeration value indicates that one or more cancellation requests have been made against the order.

NONE_REQUESTED

This enumeration value indicates that no cancellation requests have been made against the order.

LineItemFulfillmentStatus:

FULFILLED

The line item has been processed, packaged, and shipped. Note:A line item is considered fulfilled as soon as any one unit or component of the line item is assigned to a fulfillment.

IN_PROGRESS

Applies only to orders with more than one line item. Indicates the seller has begun packaging and shipping one or more line items from the order, but not all line items have been shipped.

NOT_STARTED

The seller has not yet begun packaging the line item.

OrderFulfillmentStatus

FULFILLED

The entire order has been shipped. Note:When any quantity of a line item is assigned to a fulfillment, that line item is marked asFULFILLED, even if the total quantity of the line item has not yet shipped.

IN_PROGRESS

Applies only to orders with more than one line item. Indicates the seller has begun packaging and shipping line items from the order, but not all line items have been shipped.

NOT_STARTED

The seller has not yet begun packaging any line items from the order.

OrderPaymentStatus

FAILED

This enumeration value indicates that buyer payment or refund has failed.

FULLY_REFUNDED

This enumeration value indicates that the full amount of the order has been refunded to the buyer. This value is only applicable to return requests or order cancellations.

PAID

This enumeration value indicates that the order is fully paid.

PARTIALLY_REFUNDED

This enumeration value indicates that a partial amount of the order has been refunded to the buyer.

PENDING

This enumeration value indicates that buyer payment or a refund from the seller is is in the pending state.

By default our orders will be downloaded with NONE_REQUESTED NOT_STARTED NOT_STARTED PAID This is indicates that the order is Ready For Shipping

If the payment is not cleared then NONE_REQUESTED NOT_STARTED NOT_STARTED PENDING This is indicates that the order is Pending

Once we ship the order we set NONE_REQUESTED FULFILLEDFULFILLED PAID This indicates that the order is Shipped

If we would like to cancel the order: CANCELED NOT_STARTED NOT_STARTED PAID This indicates that the order is Canceled

If we would like to partialy refund an order NONE_REQUESTED FULFILLEDFULFILLED PARTIALLY_REFUNDED This indicates that the order is partially refunded and status remains as Shipped

If we would like to fully refund an order NONE_REQUESTED FULFILLED FULFILLED FULLY_REFUNDED This indicates that the order is fullt refunded and status is changed as Canceled

Primary Fulfillment API objects

Objects are as follows:

Order

The Order object contains information about an order that requires shipping, including:

  • Information about the buyer and seller
  • Information about the order’s line items
  • The plans for packaging, addressing and shipping the order
  • The status of payment, packaging, addressing, and shipping the order
  • A summary of monetary amounts specific to the order, such as pricing, payments, and shipping costs

Line Item

The LineItem object contains details about one or more units of a sold item in an order, including:

  • Information about the item's eBay listing, including listing title, promotions, and the seller's SKU
  • All monetary amounts specific to the line item such as pricing, promotions, delivery costs, fees, taxes, and refunds
  • The status of packaging, addressing and shipping the line item

Shipping Fulfillment

The ShippingFulfillment object contains information about one package and its delivery, including:

  • The plans for packaging, addressing and shipping a set of line items
  • The history of the fulfillment
  • Shipping and tracking details of the fulfillment
  • Estimated and actual delivery dates

Fulfillment Start Instruction

The FulfillmentStartInstruction object contains recommendations for fulfilling an order, including:

  • The type of fulfillment
  • The shipping carrier and service
  • Recipient contact and address information
  • The estimated delivery window

Issue Refund Request

The request payload of theissueRefundmethod allows sellers (enrolled in eBay managed payments) to:

  • Issue a full or partial refund
  • Issue a refund for an entire order, or for one or more line items in a multiple line item order
  • Use legacy or REST-based identifiers for orders and order line items

Get Payment Dispute Summary

ThegetPaymentDisputeSummariesresponse includes summary information about one or more buyer-initiated payment disputes opened against the seller's order(s). The seller has the option of retrieving all payment disputes against their account, or they can use query parameters to retrieve payment disputes in a certain state (open, closed, or 'action needed'), payment disputes created during a specified time period, payment disputes created by a specific buyer, or payment disputes opened against a specific order.

Get Payment Dispute Details

ThegetPaymentDisputeresponse includes detailed information about a specific payment dispute. The payment dispute is identified through a call URI path parameter. Information in thegetPaymentDisputeresponse includes the status of the payment dispute, the reason why the buyer opened the payment dispute, the order and line items associated with the payment dispute, and the dollar amount involved in the payment dispute. Other details in the response will vary based on the status of the dispute.

Get Payment Dispute Activity

ThegetActivitiesresponse shows all actions that have occurred for a specific payment dispute, from the dispute being opened to the dispute being closed. For each action, there is a timestamp for when the action occured and it states the actor (buyer, seller, system) that performed the action.

Get Evidence File

In thefetchEvidenceContentmethod, the seller identifies the payment dispute, evidence set, and evidence file (using path and query parameters) to retrieve an evidence file that was provided to support the seller's case against the payment dispute.

API restrictions

Supported marketplaces

The order and fulfillment methods of the Fulfillment API are supported on all eBay marketplaces that support selling and order management, including the following:

Rate limits

The number of calls you can make per day using the Fulfillment API depends on your application's eBay compatibility level:

  • All applications:100,000 calls/day
  • eBay compatible applications:2,500,000 calls/day

API Calls and Structure

getOrder

GET /order/{orderId}

Use this call to retrieve the contents of an order based on its unique identifier,orderId. This value was returned in the getOrders call's orders.orderId field when you searched for orders by creation date, modification date, or fulfillment status More details are available here

getOrders

GET /order

Use this call to search for and retrieve one or more orders based on their creation date, last modification date, or fulfillment status using the filter parameter. You can alternatively specify a list of orders using the orderIds parameter. More details are available here

issueRefund

POST /order/{order_id}/issue_refund

This method allows a seller (opted in to eBay Managed Payments) to issue a full or partial refund to a buyer for an order. Full or partial refunds can be issued at the order level or line item level.

The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequentgetOrdercall to check the status of the refund. The status of an order refund can be found in thepaymentSummary.refunds.refundStatusfield of thegetOrderresponse. More details are available here

shipping_fulfillment

createShippingFulfillment

POST /order/{orderId}/shipping_fulfillment

When you group an order's line items into one or more packages, each package requires a corresponding plan for handling, addressing, and shipping; this is ashipping fulfillment. For each package, execute this call once to generate a shipping fulfillment associated with that package.

Note:A single line item in an order can consist of multiple units of a purchased item, and one unit can consist of multiple parts or components. Although these components might be provided by the manufacturer in separate packaging, the seller must include all components of a given line item in the same package.

Before using this call for a given package, you must determine which line items are in the package. If the package has been shipped, you should provide the date of shipment in the request. If not provided, it will default to the current date and time.

More details are available here

getShippingFulfillment

POST /order/{orderId}/shipping_fulfillment/{fulfillmentId}

Use this call to retrieve the contents of a fulfillment based on its unique identifier,fulfillmentId(combined with the associated order'sorderId). ThefulfillmentIdvalue was originally generated by thecreateShippingFulfillmentcall, and is returned by thegetShippingFulfillmentscall in themembers.fulfillmentIdfield.

More details are available here

getShippingFulfillments

GET /order/{orderId}/shipping_fulfillment

Use this call to retrieve the contents of all fulfillments currently defined for a specified order based on the order's unique identifier, orderId. This value is returned in the getOrders call's members.orderId field when you search for orders by creation date or shipment status. More details are available here

getPaymentDispute

GET /payment_dispute/{payment_dispute_id}

This method retrieves detailed information on a specific payment dispute. The payment dispute identifier is passed in as path parameter at the end of the call URI.

Below is a summary of the information that is retrieved:

  • Current status of payment dispute
  • Amount of the payment dispute
  • Reason the payment dispute was opened
  • Order and line items associated with the payment dispute
  • Seller response options if an action is currently required on the payment dispute
  • Details on the results of the payment dispute if it has been closed
  • Details on any evidence that was provided by the seller to fight the payment dispute

More details are available here

Is this article helpful?
0 0 0