> This page is for Afterpay Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.afterpay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.afterpay.com/_mcp/server.

# Set Up Custom Rates

Do the following to successfully approve a new custom rate and assign it to a specific merchant, or a series of merchants grouped together via the same brand:

1. The Afterpay team creates a new custom rate. This outlines the buy rate and defines whether the custom rate is eligible for a specific merchant or multiple merchants via a brand identifier. A custom rate can contain one or more buy rates depending on the number of countries that require custom rates.

2. Once the custom rate is created, you, the partner, must approve or reject the proposed custom rate via [Approve Custom Rate](https://afterpay.docs.buildwithfern.com/afterpay-partner-api/guides/technical-guides/welcome/introduction). The `customRateId` for the pending custom rate is provided by the Afterpay team or you can listen to [webhooks](/afterpay-partner-api/api-reference/reference-partner-api/rates/custom-rate-created) for custom rate creation events.

```curl
curl --location 'https://agencyapi.afterpay.com/v1/custom-rate/{{customRateId}}/review' \
--header 'X-Afterpay-Request-Signature: <Request Signature>' \
--header 'X-Afterpay-Request-Date: <Request Date>' \
--header 'X-Afterpay-Request-Apikey: <API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{ 
"customRateId": "UUID", 
"userDetails": { 
  "firstName": "John", 
  "lastName": "Doe", 
  "email": "john.doe@psp.com" 
}, 
"comment": "Approved for xyz reason", 
"status": "APPROVED", 
"customRateType": "MERCHANT", 
"reference": "MerchantReference", 
"rateDetails": [ { 
  "countryCode": "US", 
  "rates": [ 
  { 
    "variableRatePercentage": "1.5", 
    "fixedRate": "0.15", "fixedRateCurrencyCode": "USD", 
    "rateType": "INTRODUCTORY", 
    "durationInMonths": 1 
  }, 
  { 
    "variableRatePercentage": "3.5", 
    "fixedRate": "0.3", 
    "fixedRateCurrencyCode": "USD", 
    "rateType": "ONGOING" 
  } 
] }, { 
    "countryCode": "CA", 
    "rates": [ 
    { 
      "variableRatePercentage": "4.5", 
      "fixedRate": "0.45", 
      "fixedRateCurrencyCode": "CAD", 
      "rateType": "ONGOING" } 
    ] } 
] }'
```

3. The custom rate is assigned to a specific merchant via the `customRateType` field and the `reference` field. The `merchantReference` field is unique and can only be associated with a single merchant. The `brandReference` field can be associated with multiple merchants and typically represents a platform.

a. If the `customRateType` field is set to MERCHANT, set the `reference` field to the same value as the merchant onboarding’s `merchantReference` field.

b. If the `customRateType` field is set to BRAND, set the reference field to the same value as the merchant onboarding’s business `brandReference`.

```curl
curl --location 'https://agencyapi.afterpay.com/v1/onboardings/' \
--header 'X-Afterpay-Request-Signature: <Request Signature>' \
--header 'X-Afterpay-Request-Date: <Request Date>' \
--header 'X-Afterpay-Request-Apikey: <API Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
 "merchantCountry": "US",
 "merchantReference": "merchantId1234",
 "settlementContractId": "1eR1bWHtIRdmyJNwEgqmlSI58sZ",
 "parameters": {
       "business":{
           "address":{
               "address1": "1 Market Street",
               "city": "San Francisco",
               "state": "CA",
               "postCode": "94105",
               "countryCode": "US"
           }
           ,"businessType":"sole_proprietorship",
           "customerSupportPhoneNumber":"7700900077",
           "email":"test@afterpay.com",
           "legalBusinessName":"Test Merchant, LLC",
           "merchantCategoryCode":"5072",
           "tradingCountry":"US",
           "tradingName":"Test Merchant",
           "websiteUrl":"https://www.testmerchant.com",
	    "brandReference": "platformId1234"
       },
	"channels":{
		online: true
	},
"owners":[
           {
               "firstName":"John",
               "lastName":"Smith"
           }
       ]
 }
}'
```