Transfers API v2024-06-01 reference

Overview

Use the Transfers API v2024-06-01 to initiate payouts for your seller accounts. This API is available in private beta only.

Version information

Version : 2024-06-01

Contact information

Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html

License information

License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0

URI scheme

Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS

Consumes

application/json

Produces

application/json

Operations

initiatePayout
getPaymentMethods

Paths

POST /finances/transfers/2024-06-01/payouts

Operation: initiatePayout

Description

Initiates an on-demand payout to the seller's default deposit method in Seller Central for the given marketplaceId and accountType (if eligible). Only one on-demand payout can be initiated for each marketplace and account type within a 24-hour period.

Usage Plan:

Rate (requests per second)	Burst
0.5	30

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that are applied to the requested operation. The preceding table shows the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may yield higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.

Parameters

Type	Name	Description	Schema
Body	body required	The request body for the `initiatePayout` operation.	InitiatePayoutRequest

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	InitiatePayoutResponse
400	Request has missing or invalid parameters and cannot be parsed. Possible values include: INVALID_INPUT: The marketplaceId/accountType provided in the input is invalid. NOT_ELIGIBLE_FOR_ON_DEMAND_PAYOUT: The seller is not eligible for On-Demand Payouts. Retries would most likely fail. NO_DEPOSIT_METHOD: No deposit method found for the selling partner. Please add a valid deposit method and try again. INSUFFICIENT_PAYOUT_AMOUNT: The outstanding balance is less than the minimum permissible payout amount, hence no payout will be initiated. PAYOUT_FREQUENCY_EXCEEDED: This occurs if there has already been a payout initiated for the given marketplace and accountType in the last 24 hours. A selling partner can request payout once in every 24 hours for a given marketplace and accountType. Note: The error codes listed here are not an exhaustive representation. The API's error handling is subject to change, and additional error codes may be introduced in the future. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	ErrorList

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Example HTTP request

Request body

{
  "body" : {
    "marketplaceId" : "APJ6JRA9NG5V4",
    "accountType" : "Standard Orders"
  }
}

Example HTTP response

Response 200

{
  "payoutReferenceId" : "3DM7DQi8DPAMOLOSaN5HxT0q2waNwH95fopx3AD2Lgc"
}

POST /finances/transfers/2024-06-01/paymentmethods

Operation: getPaymentMethods

Description

The list of payment methods added for a particular seller. These payment methods can be used for payouts.

Parameters

Type	Name	Description	Schema
Body	body required	The request schema of the `getPaymentMethods` operation.	GetPaymentMethodsRequest

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	GetPaymentMethodsResponse
400	Request has missing or invalid parameters and cannot be parsed. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	ErrorList

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Example HTTP request

Request body

{
  "body" : {
    "owningCustomerId" : "ACUULBDVZHYZZ",
    "marketplaceId" : "ATVPDKIKX0DER",
    "requestId" : "Rufus",
    "paymentMethodFilter" : {
      "subscribedMarketplaces" : [ "ATVPDKIKX0DER" ],
      "assignmentFilter" : {
        "assignmentTypes" : [ "DEFAULT" ]
      }
    }
  }
}

Example HTTP response

Response 200

{
  "piDetails" : [ {
    "countryCode" : "US",
    "defaultMarketplaces" : [ "ATVPDKIKX0DER" ],
    "encryptedAccountHolderName" : "?SIEGE|Rufus!00AAAAAAYIARAAGgAAAAAADgjowvyyBhAAGAAgADIAAAAAkQAAAAAAAAAA1goTnyZO5d+yqPgsktNT/nEAAAAAAAAAP0MonpF3YDVi4nembq6SlQ+4vdiDYdw3yAQnHXMw7xQtF7vzrLY/MJPd3nisz3cIf8mXj5Q6OLDmVukyrqBS0ZDq12OuNAqwh3O1w/tAba31f7UBWfhg3XJFwflqHOX028hd7wmGl72o9NNk6ylY18g=!EGEIS?",
    "paymentInstrumentId" : "0h_TU_CUS_4058fe2a-da6b-4b82-8e48-b20ff2eb4f6d",
    "paymentInstrumentType" : "CARD",
    "expiryDate" : {
      "month" : "3",
      "year" : "2029"
    },
    "tail" : "677"
  } ]
}

Error Responses and Schemas

This table contains HTTP status codes and associated information for error responses.

HTTP Code	Description	Schema
403	Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
404	The resource specified does not exist. Headers: `x-amzn-RateLimit-Limit` (string):Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
413	The request size exceeded the maximum accepted size. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
415	The request payload is in an unsupported format. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
429	The frequency of requests was greater than allowed. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
500	An unexpected condition occurred that prevented the server from fulfilling the request. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
503	Temporary overloading or maintenance of the server. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList

Definitions

InitiatePayoutRequest

The request schema for the initiatePayout operation.

Name	Description	Schema
marketplaceId required	A marketplace identifier. For the list of possible marketplace identifiers, refer to Marketplace IDs.	string
accountType required	The account type in the selected marketplace for which a payout has to be initiated. For the supported EU marketplaces, the only account type is `Standard Orders`.	string

InitiatePayoutResponse

The response schema for the initiatePayout operation.

Name	Description	Schema
payoutReferenceId required	The financial event group ID for a successfully initiated payout. You can use this ID to track payout information.	string

GetPaymentMethodsRequest

The request schema for the getPaymentMethods operation.

Name	Description	Schema
owningCustomerId optional	The customer ID of the seller.	StringWithNoWhiteSpace
marketplaceId optional	The marketplace identifier.	StringWithNoWhiteSpace
requestId optional	The marketplace identifier.	StringWithNoWhiteSpace
paymentMethodFilter optional	The object used to filter payment methods based on different factors.	PaymentMethodFilter

GetPaymentMethodsResponse

The response schema for the getPaymentMethodsResponse operation.

Name	Description	Schema
piDetails optional	The list of payment instruments.	ListOfPIDetails

PaymentMethodFilter

The object used to filter payment methods based on different factors.

Name	Description	Schema
paymentInstrumentId optional	The payment instrument identifier.	StringWithNoWhiteSpace
subscribedMarketplaces optional	The payment instrument identifier.	ListOfStrings
assignmentFilter optional	The filter that returns the default payment instrument(s).	AssignmentFilter
paymentInstrumentTypes optional	The list of payment instrument types.	ListOfPaymentInstrumentType

AssignmentFilter

The list of default payment instruments that are returned when you use the assignmentFilter.

Name	Description	Schema
assignmentTypes optional	The list of assignment types.	ListOfAssignmentType

ListOfAssignmentType

The list of assignment types.

Type : < AssignmentType > array

AssignmentType

The filter that returns payment methods based on the type of assignment.

Type : enum

Value	Description
DEFAULT	The payment instrument that is used as the primary payout method.

ListOfPIDetails

The list of payment instruments.

Type : < PIDetails > array

PIDetails

The details of a payment instrument.

Name	Description	Schema
encryptedAccountHolderName optional	The encrypted account holder name that is registered for the payment instrument.	StringWithNoWhiteSpace
paymentInstrumentId optional	The payment instrument identifier.	StringWithNoWhiteSpace
tail optional	The last three or four digits of the payment instrument.	StringWithDigits
expiryDate optional	The expiration date of a card used for payment.	ExpiryDate
countryCode optional	The two-letter country code that follows the ISO 3166-1 alpha-2 standard. For payment methods in the `card` category, the code is for the country where the card was issued. For payment methods in the `bank account` category, the code is for the country where the account is located.	StringWithNoWhiteSpace
defaultMarketplaces optional	The list of marketplaces where the the payment instrument is marked as `default`. The selected payment instrument activates payouts for these marketplaces.	ListOfStrings
paymentInstrumentType optional	The payment instrument type.	PaymentInstrumentType

ExpiryDate

The expiration date of a card used for payment. If the payment instrument is not a card, the expiration date is null.

Name	Description	Schema
month optional	Month	StringWithDigits
year optional	Year	StringWithDigits

ListOfPaymentInstrumentType

The list of payment instrument types that are present.

Type : < PaymentInstrumentType > array

PaymentInstrumentType

The payment instrument type.

Type : enum

Value	Description
BANK_ACCOUNT	Bank Account.
CARD	Card
SELLER_WALLET	Seller Wallet Virtual Bank Account.

ListOfStrings

A list of strings.

Type : < StringWithNoWhiteSpace > array

StringWithDigits

A string with digits

Type : string

Pattern : ^[0-9]*

StringWithNoWhiteSpace

A string with no white spaces.

Type : string

Pattern : \S+

ErrorList

A list of error responses returned when a request is unsuccessful.

Name	Description	Schema
errors required	array of errors Example : `[ {<br> "code" : "InvalidInput",<br> "message" : "The input request had one or more invalid input parameters."<br>} ]`	< Error > array

Error

Error response returned when the request is unsuccessful.

Name	Description	Schema
code required	An error code that identifies the type of error that occurred. Example : `"InvalidInput"`	string
message required	A message that describes the error condition. Example : `"The input request had one or more invalid input parameters."`	string
details optional	Additional details that can help the caller understand or fix the issue. Example : `"The following input parameters are invalid : [ marketplaceId ]."`	string