> 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 Default and Tier Rates

Do the following to successfully approve a new rate contract and assign a merchant to a tier rate:

1. The Afterpay team creates a new contract that outlines the default buy rate as well as any additional tiers with their associated buy rates and GMV ranges. There is one contract per country and the contract remains active until it is explicitly deprecated.

2. Once the contract is created, you, the partner, must approve or reject the proposed rate contract via Approve Contract. Afterpay can provide the `contractId` for the pending contract or you can listen to [webhooks](/afterpay-partner-api/api-reference/reference-partner-api/rates/contract-created) for contract creation events.

```curl
curl --location 'https://agencyapi.afterpay.com/v1/rates-contract/{{contractId}}/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 '{
"contractId": {{contractId}},
"userDetails": {
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@psp.com"
},
"comment": "LGTM",
"status": "APPROVED",
"countryCode": "US",
"buyRates": {
   "defaultRates": {
     "variableRatePercentage": "6",
     "fixedRate": "0.30",
     "fixedRateCurrencyCode": "USD",
     "rateType": "ONGOING"
   },
   "tierDetails": [
     {
       "tier": "1",
       "minimumGmv": "0",
       "maximumGmv": "1000000",
       "gmvCurrencyCode": "USD",
       "tieredRates": [
         {
           "variableRatePercentage": "5",
           "fixedRate": "0.30",
           "fixedRateCurrencyCode": "USD",
           "rateType": "ONGOING"
         }
       ]
     },
     {
       "tier": "2",
       "minimumGmv": "1000001",
       "maximumGmv": "10000000",
       "gmvCurrencyCode": "USD",
       "tieredRates": [
         {
           "variableRatePercentage": "4",
           "fixedRate": "0.30",
           "fixedRateCurrencyCode": "USD",
           "rateType": "ONGOING"
         }
       ]
     },
     {
       "tier": "3",
       "minimumGmv": "10000001",
       "maximumGmv": "100000000",
       "gmvCurrencyCode": "USD",
       "tieredRates": [
         {
           "variableRatePercentage": "3",
           "fixedRate": "0.30",
           "fixedRateCurrencyCode": "USD",
           "rateType": "ONGOING"
         }
       ]
     }
   ]
 }
}
'
```

3. Once a contract is successfully approved, you, the partner, can assign merchants to tiers associated with the approved contract using [Update Tier](https://afterpay.docs.buildwithfern.com/afterpay-partner-api/guides/technical-guides/welcome/introduction) only.

> **Note**
>
> You can use both the [UpdateOnboarding](/afterpay-partner-api/api-reference/reference-partner-api/onboardings/update-onboarding) or [UpdateTier](/afterpay-partner-api/api-reference/reference-partner-api/rates/update-rate) endpoints to set the initial tier for a merchant. For subsequent tier updates, use the [UpdateTier](/afterpay-partner-api/api-reference/reference-partner-api/rates/update-rate) endpoint.

```curl
curl --location --request PUT 'https://agencyapi.afterpay.com/v1/onboardings/{{onboardingId}}/capabilities/buy-rate' \
--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 '{ 
"tier": 1, 
"gmv": "10000000", 
"gmvCurrencyCode": "USD", 
"agencyMerchantContractDetails": { 
  "contractId": "{{partner-generated contractId}}", 
  "contractDate": "2023-09-17T00:00:00.000+00:00" } 
}'
```

4. If a merchant’s tier needs to be updated, use [Update Tier](https://afterpay.docs.buildwithfern.com/afterpay-partner-api/guides/technical-guides/welcome/introduction) to update the merchant’s associated tier and GMV.

> **Notes**
>
> Step 4: Tier updates require a unique partner-generated contract ID and can only be updated for a specific merchant once per quarter.
>
> When a merchant's tier is updated through [UpdateTier](/afterpay-partner-api/api-reference/reference-partner-api/rates/update-rate), the `agencyMerchantContractDetails.contractId` refers to a unique identifier for a contract. This contract is between the Payment Service Provider and the merchant and represents the Afterpay rate change. This `contractId` is different from the `contractId` specified for custom rates and can only be updated once per quarter.