openapi: 3.0.0 info: title: Rate Table API description: This API allows sellers to retrieve and manage their custom shipping rate tables. In addition, this API also provides sellers in mainland China methods to configure split-payouts between two separate payment instruments. contact: name: eBay Inc, license: name: eBay API License Agreement url: https://go.developer.ebay.com/api-license-agreement version: 2.1.0 servers: - url: https://api.ebay.com{basePath} description: Production variables: basePath: default: /sell/account/v2 paths: /rate_table/{rate_table_id}: get: tags: - rate_table description: This method retrieves an existing rate table identified by the rate_table_id path parameter.

getRateTable currently supports the retrieval of rate tables for the following eBay marketplace IDs: A successful call returns detailed information for the specified shipping rate table. operationId: getRateTable parameters: - name: rate_table_id in: path description: This path parameter is the unique identifier for the shipping rate table to retrieve.

Use the getRateTables method of the Account API v1 to retrieve rate table IDs. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RateTableDetails' '400': description: Bad Request x-response-codes: errors: '394001': domain: API_ACCOUNT category: REQUEST description: The specified rate table ID is invalid. Please input a valid rate table ID. The getRateTables method can be used to retrieve valid rate table IDs '404': description: Not found '500': description: Internal Server Error x-response-codes: errors: '395000': domain: API_ACCOUNT category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.account - https://api.ebay.com/oauth/api_scope/sell.account.readonly /rate_table/{rate_table_id}/update_shipping_cost: post: tags: - rate_table description: This method allows sellers to update shippingCost and/or additionalCost information for an existing shipping rate table identified by the rate_table_id path parameter.

A successful call returns an HTTP status code of 204 No Content. operationId: updateShippingCost parameters: - name: rate_table_id in: path description: This path parameter is the unique identifier for the shipping rate table for which shipping costs will be updated.

Use the getRateTables method of the Account API v1 to retrieve rate table IDs. required: true schema: type: string - name: Content-Type in: header description: This header indicates the format of the request body provided by the client. It's value should be set to application/json.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: Request to update the shipping costs for the identified shipping rate table. content: application/json: schema: description: Request to update the shipping costs for the identified shipping rate table. $ref: '#/components/schemas/RateTableUpdate' required: false responses: '204': description: No Content '400': description: Bad Request x-response-codes: errors: '394001': domain: API_ACCOUNT category: REQUEST description: The specified rate table ID is invalid. Please input a valid rate table ID. The getRateTables method can be used to retrieve valid rate table IDs '394004': domain: API_ACCOUNT category: REQUEST description: Please specify at least one shipping rate entry to add/update through the rates array. '394007': domain: API_ACCOUNT category: REQUEST description: Please specify the rateId value for one or more shipping rate entries being updated. '394008': domain: API_ACCOUNT category: REQUEST description: The shippingCost containers are missing for one or more shipping rate entries. Please provide the shipping cost values for the shipping rate entries being updated. '394009': domain: API_ACCOUNT category: REQUEST description: The specified shipping cost currency does not match the currency used for the marketplace. '394011': domain: API_ACCOUNT category: REQUEST description: The additional cost containers are missing for one or more shipping rate entries for the WEIGHT/SURCHARGE rate table. Please provide these values for the additional rate entries being added/updated. '394012': domain: API_ACCOUNT category: REQUEST description: The specified additional cost currency does not match the currency used for the marketplace. '394015': domain: API_ACCOUNT category: REQUEST description: The number of rate entries must be less than or equal to the existing data. '394025': domain: API_ACCOUNT category: REQUEST description: The shipping cost value is invalid. '394026': domain: API_ACCOUNT category: REQUEST description: The additional cost value is invalid. '394035': domain: API_ACCOUNT category: REQUEST description: The shipping cost is not supported in surcharge calculation type. '394036': domain: API_ACCOUNT category: REQUEST description: Additional costs are not applicable for shipping rate tables based on shipping item. Please remove the additional cost container. '394041': domain: API_ACCOUNT category: REQUEST description: The rateId of rates is repeated. '404': description: Not Found '409': description: Conflict '500': description: Internal Server Error x-response-codes: errors: '395000': domain: API_ACCOUNT category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.account /payout_settings: get: tags: - payout_settings description: '

Important! Split-payout functionality is only available to mainland China sellers, who can split payouts between their Payoneer account and bank account. Card payouts are not currently available for sellers in mainland China.


This method returns details on two payment instruments defined on a seller''s account, including the ID, type, status, nickname, last four digits of the account number, and payout percentage for the instruments.

Using the instrumentId returned with this method, sellers can makes changes to the payout split of the instruments with the updatePayoutPercentage method. Note that the instrumentStatus of a payment instrument, also returned using this method, must be ACTIVE in order to do split payouts on that payment instrument.' operationId: getPayoutSettings responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PayoutSettingsResponse' '500': description: Internal Server Error x-response-codes: errors: '395000': domain: API_ACCOUNT category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.finances /payout_settings/update_percentage: post: tags: - payout_settings description: '

Important! Split-payout functionality is only available to mainland China sellers, who can split payouts between their Payoneer account and bank account. Card payouts are not currently available for sellers in mainland China.


This method allows sellers in mainland China to configure the split-payout percentage for two payout instruments available for seller payouts. For example, a seller can split payouts to have 70% of the payout go to a bank account and 30% go to a Payoneer account.

Note: The split-payout percentage must always add up to 100%. If the values do not equal 100, the call will fail. Instruments cannot be added/removed using Finance and Account APIs.
Users can specify the payout instruments being updated by using the instrumentId associated with each payment instrument in the request payload. This value is returned by using the getPayoutSettings method. Users can specify the percentage of the payout allocated to each instrument using the payoutPercentage request field. This value must be a whole number and cannot exceed 100.

For more details on configuring split-payout percentages, see Mainland China Split Payout Playbook. ' operationId: updatePayoutPercentage parameters: - name: Content-Type in: header description: This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdatePayoutPercentageRequest' required: false responses: '204': description: No Content '400': description: Bad Request x-response-codes: errors: '394100': domain: API_ACCOUNT category: REQUEST description: The seller is not eligible to set split-payout percentage. '394101': domain: API_ACCOUNT category: REQUEST description: Missing instrumentId in request. '394102': domain: API_ACCOUNT category: REQUEST description: Missing payoutPercentage in request. '394103': domain: API_ACCOUNT category: REQUEST description: 'The ''payoutPercentage'' {payoutPercentage} is not valid. The payout percentage should be an integer value. Minimum value: {0}, Maximum value: {100}.' '394104': domain: API_ACCOUNT category: REQUEST description: Duplicate instrumentId in request. '394105': domain: API_ACCOUNT category: REQUEST description: Sum up of 'payoutPercentage' in request must be equal to 100, current value {payoutPercentage}. '394106': domain: API_ACCOUNT category: REQUEST description: Instrument 'instrumentId' {instrumentId} not found. '394107': domain: API_ACCOUNT category: REQUEST description: Instrument 'instrumentId' {instrumentId} missing in request. '500': description: Internal Server Error x-response-codes: errors: '395000': domain: API_ACCOUNT category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. '395100': domain: API_ACCOUNT category: APPLICATION description: There was an internal error, please try again after sometime. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.finances components: schemas: Amount: type: object properties: currency: type: string description: The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD. For implementation help, refer to eBay API documentation value: type: string description: The monetary amount in the specified currency. description: A complex type that describes the value of a monetary amount as represented by a global currency. Error: type: object properties: category: type: string description: Identifies the type of erro. domain: type: string description: Name for the primary system where the error occurred. This is relevant for application errors. errorId: type: integer description: A unique number to identify the error. format: int32 inputRefIds: type: array description: An array of request elements most closely associated to the error. items: type: string longMessage: type: string description: A more detailed explanation of the error. message: type: string description: Information on how to correct the problem, in the end user's terms and language where applicable. outputRefIds: type: array description: An array of request elements most closely associated to the error. items: type: string parameters: type: array description: An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned. items: $ref: '#/components/schemas/ErrorParameter' subdomain: type: string description: 'Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.' description: This type defines the fields that can be returned in an error. ErrorParameter: type: object properties: name: type: string description: The object of the error. value: type: string description: The value of the object. PayoutInstrument: type: object properties: accountLastFourDigits: type: string description: The last four digits of the account that the seller uses to receive payouts. This may be the last four digits of a bank account or a payment processor account such as Payoneer. instrumentId: type: string description: The unique reference identifier for a payout instrument. The instrumentId is needed to change the split-payout percentages through an updatePayoutPercentage request. instrumentStatus: type: string description: The status of a payout instrument. Valid payout instrument statuses include:

See InstrumentStatusEnum for more details on each instrument status value.

Note: Payment accounts can only receive payouts if the status of a payout instrument is ACTIVE. For implementation help, refer to eBay API documentation instrumentType: type: string description: 'The type of account that received payouts. The value returned in this field may be:

Note: Only Payoneer is currently supported for sellers in mainland China. Card payouts are not currently available for sellers in mainland China. ' nickname: type: string description: When instrumentType returns BANK, this value is the seller-provided nickname that the seller uses to represent the bank account that receives the payout.

When instrumentType returns CARD, this value is the debit card network for the debit card that receives the payout.

When instrumentType returns a provider of digital wallet or payment processing services, the value returned is the name of the service provider (e.g., PAYONEER)

Note: Only Payoneer is currently supported for sellers in mainland China. Card payouts are not currently available for sellers in mainland China. payoutPercentage: type: string description: The current payout percentage allocated to an instrument. For example, 50 indicates that 50% of the payout goes to the instrument. description: This type is used to provide details about one or two of the seller's accounts that are enabled to receive payouts. PayoutSettingsResponse: type: object properties: payoutInstruments: type: array description: This array provides details about the seller's accounts defined for the seller's account.

Payment accounts can only receive payouts if the status of the payout instrument is ACTIVE. items: $ref: '#/components/schemas/PayoutInstrument' description: The base response type of the getPayoutSettings method. Rate: type: object properties: additionalCost: description: 'An additional shipping cost added to the base shipping rate (i.e., shippingCost).

This amount applies only to the following rateTableBasis options:This field is returned only when it is applicable to the specified rate ID.' $ref: '#/components/schemas/Amount' rateId: type: string description: The unique identifier for rate information.

Note: This is a string that is automatically assigned by the system when a rate object is created. shippingCategory: type: string description: 'Indicates the level of shipping service to which the shipping rate information applies.

Available shipping categories are: For implementation help, refer to eBay API documentation' shippingCost: description: 'Specifies the base shipping rate for an item.

This amount applies only to the following rateTableBasis options:' $ref: '#/components/schemas/Amount' shippingRegionNames: type: array description: An array of Region names to which the shipping rate information applies.

Returned values may be: items: type: string shippingServiceCode: type: string description: An enum value that indicates the shipping service used for the specified shipping rate. These enum values align with ShippingService metadata returned by a GeteBayDetails call with DetailName set to shippingServiceDetails. description: This container details shipping rate information identified by a unique rate ID. A successful call returns the requested shipping rate information. RateTableDetails: type: object properties: marketplaceId: type: string description: Identifies the eBay marketplace to which the shipping rate table applies. For implementation help, refer to eBay API documentation name: type: string description: The seller-defined name for the shipping rate table. Names must be unique for each table assigned to the same seller, shippingOptionType, and eBay marketplace.

Max length: 50 rates: type: array description: An array of rate objects associated with the specified shipping rate table. Each rate object is identified by a unique system-generated ID and defines specific shipping rate information. items: $ref: '#/components/schemas/Rate' rateTableBasis: type: string description: 'The rate calculation type provides three methods of calculating the shipping cost based on the seller''s selection/input: For implementation help, refer to eBay API documentation' rateTableId: type: string description: A unique, system-generated ID assigned to the shipping rate table when it is initially created. shippingOptionType: type: string description: 'The region serviced by the shipping rate table. Valid values are: For implementation help, refer to eBay API documentation' description: This container includes all information pertaining to a shipping rate table. A successful call returns the requested shipping rate information. RateTableUpdate: type: object properties: rates: type: array description: An array of rate objects for which shippingCost and/or additionalCost are to be updated. items: $ref: '#/components/schemas/RateUpdate' description: This type is used by the request payload of the updateShippingCost method to pass updated shipping cost information for a rate table identified by rateTableId. RateUpdate: type: object properties: additionalCost: description: 'An additional shipping cost added to the base shipping rate (i.e., shippingCost).

This amount applies only to the following rateTableBasis options:This field is returned only when it is applicable to the specified rate ID.' $ref: '#/components/schemas/Amount' rateId: type: string description: The identifier for the rate object.

Note: This is a string automatically assigned by the system when the rate object is created. It cannot be changed or updated. shippingCost: description: 'This is the base shipping rate for an item.

This amount applies only to the following rateTableBasis options:' $ref: '#/components/schemas/Amount' description: This container defines the updated shipping cost information for a rate object identified by rateId.

To view a list of all rate objects and corresponding rateID values, issue getRateTable for the rate table identified by rateTableId. UpdatePayoutPercentage: type: object properties: instrumentId: type: string description: The unique reference identifier for a payout instrument. This value is returned in the getPayoutSettings response and is needed to change split-payout percentages through an updatePayoutPercentage request. payoutPercentage: type: string description: The user-defined payout percentage allocated to this instrument. For example, 50 indicates that 50% of the payout goes to this instrument.

The split-payout percentage must be a positive integer value from 0-100. The values of two instruments must always add up to 100%. If the values do not equal 100, the call will fail. description: This type allows the user to change the payout percentages for two active payment instruments. UpdatePayoutPercentageRequest: type: object properties: payoutInstruments: type: array description: This array allows the seller to set the payout split percentages for two accounts enabled to receive payouts. items: $ref: '#/components/schemas/UpdatePayoutPercentage' description: This type is used by the request payload of the updatePayoutPercentage method to allow a seller to configure the split-payout percentages for two payout instruments. securitySchemes: api_auth: type: oauth2 description: The security definitions for this API. Please check individual operations for applicable scopes. flows: authorizationCode: authorizationUrl: https://auth.ebay.com/oauth2/authorize tokenUrl: https://api.ebay.com/identity/v1/oauth2/token scopes: https://api.ebay.com/oauth/api_scope/sell.finances: View and manage your payment and order information to display this information to you and allow you to initiate refunds using the third party application https://api.ebay.com/oauth/api_scope/sell.account.readonly: View your account settings https://api.ebay.com/oauth/api_scope/sell.account: View and manage your account settings