> 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. # Update Tier PUT https://agencyapi.afterpay.com/v1/onboardings/{onboardingId}/capabilities/buy-rate Content-Type: application/json Allows partners to pass a new tier and use a new contractId between the partner and the seller for audit purposes. Reference: https://developers.afterpay.com/afterpay-partner-api/api-reference/reference-partner-api/rates/update-rate ## Servers - `https://agencyapi.afterpay.com` (Production, default) - `https://agencyapi.sandbox.afterpay.com` (Sandbox) ## Request ### Path parameters - `onboardingId` (string, required) — The ID returned during a successful create an onboarding call. ### Headers - `Accept` (string, required, default: application/json) — Specifies media types that are acceptable for the response. ### Body (application/json) This endpoint expects an object. - `tier` (integer, required) — GMV tier of the seller that informs the buy rate as defined in the commercial contract. - `gmvCurrencyCode` (string, required) — Currency of the gmv volume in ISO 4217 currency code. Please use currency that is defined in the commercial contract only (e.g., USD-equivalent volume for UK sellers). - `agencyMerchantContractDetails` (V1OnboardingsOnboardingIdCapabilitiesBuyRatePutRequestBodyContentApplicationJsonSchemaAgencyMerchantContractDetails, required) - `gmv` (integer, optional, nullable) — Actual transaction volume that informs the tier. Estimated or addressable seller volume accepted when actuals are not available. ## Response ### 200 Tier update request was successfully actioned. - `onboardingId` (string, optional) — The id that is returned during a successful create an onboarding call. - `timestamp` (string, optional) — Datetime field indicating when the tier update request was actioned, returned using the standard ISO 8601 format, in UTC Coordinated Universal Time). - `error` (string, optional) — Shows any errors encountered on the response to the contract approval call. - `message` (string, optional) — Any message that may be attached to the response. - `rateDetails` (list of RateObjDurationEffectiveFrom, optional) ## Errors ### 400 Bad Request Error Bad Request - `httpStatus` (integer, optional) - `errors` (400ResponseErrors, optional) — A human-readable message which provides more details about the error. ### 401 Unauthorized Error Unauthorized, e.g., HMAC verification failed - `timestamp` (string, optional) — Timestamp of the response. - `status` (integer, optional) — The HTTP status code. - `error` (string, optional) — Name of the error that occurred. - `message` (string, optional) — A human-readable message which provides more details about the error. - `path` (string, optional) — The attempted endpoint. ### 404 Not Found Error Not found, e.g., onboarding not found. - `timestamp` (string, optional) — Timestamp of the response, indicating when the error occurred. - `status` (integer, optional) — The HTTP status code, specifically indicating a 404 error in this case. - `error` (string, optional) — A short description of the error, typically "Not Found" for a 404 response. - `message` (string, optional) — A human-readable message providing more details about the error. - `path` (string, optional) — The attempted endpoint path that resulted in the 404 error. ### 503 Service Unavailable Error Service unavailable. - `timestamp` (string, optional) — Timestamp of the response. - `status` (integer, optional) — The HTTP status code. - `error` (string, optional) — Name of the error that occurred. - `message` (string, optional) — A human-readable message which provides more details about the error. - `path` (string, optional) — The attempted endpoint. ## Types ### V1OnboardingsOnboardingIdCapabilitiesBuyRatePutRequestBodyContentApplicationJsonSchemaAgencyMerchantContractDetails - `contractId` (string, required) — Unique ID for the contract between the partner and its seller serving as the basis for the new tier update. - `contractDate` (string, required) — Effective date and time of when the contract was signed between the partner and its seller. ### RateObjDurationEffectiveFrom - `variableRatePercentage` (string, required) — Variable part of the buy-rate in percentage format e.g. 5.00 for 5%. - `fixedRate` (string, required) — Fixed part of the buy-rate e.g. 0.30 for 30 cents. - `fixedRateCurrencyCode` (string, required) — Currency of the fixed part of the buy-rate in the three-letter ISO 4217 currency code. - `rateType` (enum, required) — Type of rate whether introductory for temporary promotional periods or ongoing for steady-state business. - Allowed values: `INTRODUCTORY`, `ONGOING` - `durationInMonths` (integer, optional) — Number of months that the introductory rate will be applied. - `effectiveFrom` (string, optional) — Effective date and time of when the rate applies. ### 400ResponseErrors A human-readable message which provides more details about the error. ## Examples **Request** ```json { "tier": 3, "gmvCurrencyCode": "USD", "agencyMerchantContractDetails": { "contractId": "785389121238", "contractDate": "2023-09-17T00:00:00.000Z" } } ``` **Response** ```json { "onboardingId": "123snc-d83jndnv-38djcxnxn", "timestamp": "2023-08-17T21:41:47.341Z", "error": "string", "message": "string", "rateDetails": [ { "variableRatePercentage": "5.00", "fixedRate": "0.30", "fixedRateCurrencyCode": "USD", "rateType": "ONGOING", "durationInMonths": 1, "effectiveFrom": "2023-09-17T21:41:47.341+00:00" } ] } ``` **SDK Code** ```python import requests url = "https://agencyapi.afterpay.com/v1/onboardings/12345769/capabilities/buy-rate" payload = { "tier": 3, "gmvCurrencyCode": "USD", "agencyMerchantContractDetails": { "contractId": "785389121238", "contractDate": "2023-09-17T00:00:00.000Z" } } headers = { "Accept": "application/json", "User-Agent": "User-Agent", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://agencyapi.afterpay.com/v1/onboardings/12345769/capabilities/buy-rate'; const options = { method: 'PUT', headers: { Accept: 'application/json', 'User-Agent': 'User-Agent', 'Content-Type': 'application/json' }, body: '{"tier":3,"gmvCurrencyCode":"USD","agencyMerchantContractDetails":{"contractId":"785389121238","contractDate":"2023-09-17T00:00:00.000Z"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://agencyapi.afterpay.com/v1/onboardings/12345769/capabilities/buy-rate" payload := strings.NewReader("{\n \"tier\": 3,\n \"gmvCurrencyCode\": \"USD\",\n \"agencyMerchantContractDetails\": {\n \"contractId\": \"785389121238\",\n \"contractDate\": \"2023-09-17T00:00:00.000Z\"\n }\n}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("User-Agent", "User-Agent") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://agencyapi.afterpay.com/v1/onboardings/12345769/capabilities/buy-rate") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Accept"] = 'application/json' request["User-Agent"] = 'User-Agent' request["Content-Type"] = 'application/json' request.body = "{\n \"tier\": 3,\n \"gmvCurrencyCode\": \"USD\",\n \"agencyMerchantContractDetails\": {\n \"contractId\": \"785389121238\",\n \"contractDate\": \"2023-09-17T00:00:00.000Z\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://agencyapi.afterpay.com/v1/onboardings/12345769/capabilities/buy-rate") .header("Accept", "application/json") .header("User-Agent", "User-Agent") .header("Content-Type", "application/json") .body("{\n \"tier\": 3,\n \"gmvCurrencyCode\": \"USD\",\n \"agencyMerchantContractDetails\": {\n \"contractId\": \"785389121238\",\n \"contractDate\": \"2023-09-17T00:00:00.000Z\"\n }\n}") .asString(); ``` ```php request('PUT', 'https://agencyapi.afterpay.com/v1/onboardings/12345769/capabilities/buy-rate', [ 'body' => '{ "tier": 3, "gmvCurrencyCode": "USD", "agencyMerchantContractDetails": { "contractId": "785389121238", "contractDate": "2023-09-17T00:00:00.000Z" } }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'User-Agent' => 'User-Agent', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://agencyapi.afterpay.com/v1/onboardings/12345769/capabilities/buy-rate"); var request = new RestRequest(Method.PUT); request.AddHeader("Accept", "application/json"); request.AddHeader("User-Agent", "User-Agent"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"tier\": 3,\n \"gmvCurrencyCode\": \"USD\",\n \"agencyMerchantContractDetails\": {\n \"contractId\": \"785389121238\",\n \"contractDate\": \"2023-09-17T00:00:00.000Z\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Accept": "application/json", "User-Agent": "User-Agent", "Content-Type": "application/json" ] let parameters = [ "tier": 3, "gmvCurrencyCode": "USD", "agencyMerchantContractDetails": [ "contractId": "785389121238", "contractDate": "2023-09-17T00:00:00.000Z" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://agencyapi.afterpay.com/v1/onboardings/12345769/capabilities/buy-rate")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```