Update info post-checkout

Call Update Charge Permission to update external merchant metadata or the recurringMetadata if subscription details change post-checkout. You can update merchantMetadata child parameters multiple times if the Charge Permission is in a Chargeable or NonChargeable state. You can update merchantMetadata child parameters if the Charge Permission is in a Closed state only if chargePermissionType is Onetime and if the child parameter value to be updated is either null or an empty string. Note that buyer communication will not reflect the updated value if the Charge Permission is in a Closed state.

Request


curl "https://pay-api.amazon.com/:version/chargePermissions/:chargePermissionId" \

-X PATCH

-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

-H "x-amz-pay-date:20201012T235046Z"

-d @request_body


curl "https://pay-api.amazon.com/:environment/:version/chargePermissions/:chargePermissionId" \

-X PATCH

-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"

-H "x-amz-pay-date:20201012T235046Z"

-d @request_body

Request body

{
     "merchantMetadata": {
        "merchantReferenceId": "123-77-876", 
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "merchantNoteForBuyer",
        "customInformation": "This is custom information"  
    },
     "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "14",
            "currencyCode": "USD"
        }
    }
}

Request parameters

Name	Location	Description
chargePermissionId (required) Type: string	Path Parameter	Charge Permission identifier
recurringMetadata Type: recurringMetadata	Body	Metadata about how the recurring Charge Permission will be used. Amazon Pay only uses this information to calculate the Charge Permission expiration date and in buyer communication Note that it is still your responsibility to call Create Charge to charge the buyer for each billing cycle
merchantMetadata Type: merchantMetadata	Body	Merchant-provided order details See update info post-checkout for limits to how many times this value can be modified

Sample Code

<?php

    include 'vendor/autoload.php';

    $amazonpay_config = array(
        'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
        'private_key'   => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
        'region'        => 'YOUR_REGION_CODE',
        'algorithm'     => 'AMZN-PAY-RSASSA-PSS-V2'
    );

    $payload = array(
        'merchantMetadata' => array(
            'merchantReferenceId' => '123-77-876',
            'merchantStoreName' => 'AmazonTestStoreFront',
            'noteToBuyer' => 'merchantNoteForBuyer',
            'customInformation' => 'This is custom information'
        ),
        'recurringMetadata' => array(
            'frequency' => array(
                'unit' => 'Month',
                'value' => '1'
            ),
            'amount' => array(
                'amount' => '30',
                'currencyCode' => 'USD'
            )
        )
    );
    
    $headers = array('x-amz-pay-Idempotency-Key' => uniqid());

    try {
        $client = new Amazon\Pay\API\Client($amazonpay_config);

        $result = $client->updateChargePermission('S01-5105180-3221187', $payload);
        
        if ($result['status'] === 200) {
            $response = json_decode($result['response'], true);
            
        } else {
            // check the error
            echo 'status=' . $result['status'] . '; response=' . $result['response'];
        }
    } catch (Exception $e) {
        // handle the exception
        echo $e;
    }
?>

using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
using Amazon.Pay.API.WebStore.ChargePermission;

public class Sample
{
    public WebStoreClient InitiateClient()
    {
        // set up config
        var payConfiguration = new ApiConfiguration
        (
            region: Region.UnitedStates,
            publicKeyId: "YOUR_PUBLIC_KEY_ID",
            privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
            algorithm: AmazonSignatureAlgorithm.V2
        );

        // init API client
        var client = new WebStoreClient(payConfiguration);

        return client;
    }

    public void UpdateChargePermission()
    {
        // prepare the request
        var chargePermissionId = "S01-5105180-3221187";
        var request = new UpdateCheckoutSessionRequest()
        {
            RecurringMetadata =
            {
                Frequency = { 
                  Unit = FrequencyUnit.Month, 
                  Value = 1 
                },
                Amount = { 
                  Amount = 14, 
                  CurrencyCode = Currency.USD 
                }
            },
            MerchantMetadata = { 
                MerchantReferenceId = "123-77-876", 
                MerchantStoreName = "AmazonTestStoreFront", 
                NoteToBuyer = "merchantNoteForBuyer", 
                CustomInformation = "This is custom information" 
            }
        };

        // send the request
        ChargePermissionResponse result = client.UpdateChargePermission(chargePermissionId, request);

        // check if API call was successful
        if (!result.Success)
        {
            // handle the API error (use Status field to get the numeric error code)
        }

        // do something with the result, for instance:
        State chargePermissionState = result.StatusDetails.State;
    }

}

import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Region;

import org.json.JSONObject;

// for generating an idempotency key
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

public void sample() {
    PayConfiguration payConfiguration = null;
    try {
        payConfiguration = new PayConfiguration()
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
            .setRegion(Region.NA)
            .setPrivateKey("YOUR_PRIVATE_KEY")
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = null;
        String chargePermissionId = "S01-5105180-3221187";

        JSONObject payload = new JSONObject();
        JSONObject merchantMetadata = new JSONObject();
        merchantMetadata.put("merchantReferenceId", "32-41-323141");
        merchantMetadata.put("merchantStoreName", "AmazonTestStoreName");
        merchantMetadata.put("noteToBuyer", "merchantNoteForBuyer");
        merchantMetadata.put("customInformation", "This is custom information");
        payload.put("merchantMetadata", merchantMetadata);

        JSONObject recurringMetadata = new JSONObject();

        JSONObject frequency = new JSONObject();
        frequency.put("unit","Month");
        frequency.put("value","1");
        recurringMetadata.put("frequency", frequency);

        JSONObject amount = new JSONObject();
        amount.put("amount","14");
        amount.put("currencyCode","USD");
        recurringMetadata.put("amount", amount);

        payload.put("recurringMetadata", recurringMetadata);

        response = webstoreClient.updateChargePermission(chargePermissionId, payload);
    } catch (AmazonPayClientException e) {
        e.printStackTrace();
    }
}

const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const uuidv4 = require('uuid/v4');

const config = {
    publicKeyId: 'YOUR_PUBLIC_KEY_ID',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'us',
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2' 
};    
                
const payload = {
  merchantMetadata: {
      merchantReferenceId: "123-77-876",
      merchantStoreName: "AmazonTestStoreFront",
      noteToBuyer: "merchantNoteForBuyer",
      customInformation: "This is custom information"
  },
  recurringMetadata: {
      frequency: {
          unit: "Month",
          value: "1"
      },
      amount: {
          amount: "14",
          currencyCode: "USD"
      }
  }
}
                        
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateChargePermission('S01-5105180-3221187',payload);

response.then(function (result) {
    console.log(result.data);
}).catch(err => {
    console.log(err);
});

<?php

    include 'vendor/autoload.php';

    $amazonpay_config = array(
        'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
        'private_key'   => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
        'region'        => 'YOUR_REGION_CODE',
        'sandbox'       => true,
        'algorithm'     => 'AMZN-PAY-RSASSA-PSS-V2'
    );

    $payload = array(
        'merchantMetadata' => array(
            'merchantReferenceId' => '123-77-876',
            'merchantStoreName' => 'AmazonTestStoreFront',
            'noteToBuyer' => 'merchantNoteForBuyer',
            'customInformation' => 'This is custom information'
        ),
        'recurringMetadata' => array(
            'frequency' => array(
                'unit' => 'Month',
                'value' => '1'
            ),
            'amount' => array(
                'amount' => '30',
                'currencyCode' => 'USD'
            )
        )
    );
    
    $headers = array('x-amz-pay-Idempotency-Key' => uniqid());

    try {
        $client = new Amazon\Pay\API\Client($amazonpay_config);

        $result = $client->updateChargePermission('S01-5105180-3221187', $payload);
        
        if ($result['status'] === 200) {
            $response = json_decode($result['response'], true);
            
        } else {
            // check the error
            echo 'status=' . $result['status'] . '; response=' . $result['response'];
        }
    } catch (Exception $e) {
        // handle the exception
        echo $e;
    }
?>

using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
using Amazon.Pay.API.WebStore.ChargePermission;

public class Sample
{
    public WebStoreClient InitiateClient()
    {
        // set up config
        var payConfiguration = new ApiConfiguration
        (
            region: Region.UnitedStates,
            environment: Environment.Sandbox,
            publicKeyId: "YOUR_PUBLIC_KEY_ID",
            privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
            algorithm: AmazonSignatureAlgorithm.V2
        );

        // init API client
        var client = new WebStoreClient(payConfiguration);

        return client;
    }

    public void UpdateChargePermission()
    {
        // prepare the request
        var chargePermissionId = "S01-5105180-3221187";
        var request = new UpdateCheckoutSessionRequest()
        {
            RecurringMetadata =
            {
                Frequency = { 
                  Unit = FrequencyUnit.Month, 
                  Value = 1 
                },
                Amount = { 
                  Amount = 14, 
                  CurrencyCode = Currency.USD 
                }
            },
            MerchantMetadata = { 
                MerchantReferenceId = "123-77-876", 
                MerchantStoreName = "AmazonTestStoreFront", 
                NoteToBuyer = "merchantNoteForBuyer", 
                CustomInformation = "This is custom information" 
            }
        };

        // send the request
        ChargePermissionResponse result = client.UpdateChargePermission(chargePermissionId, request);

        // check if API call was successful
        if (!result.Success)
        {
            // handle the API error (use Status field to get the numeric error code)
        }

        // do something with the result, for instance:
        State chargePermissionState = result.StatusDetails.State;
    }

}

import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Environment;
import com.amazon.pay.api.types.Region;

import org.json.JSONObject;

// for generating an idempotency key
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

public void sample() {
    PayConfiguration payConfiguration = null;
    try {
        payConfiguration = new PayConfiguration()
            .setPublicKeyId("YOUR_PUBLIC_KEY_ID")
            .setRegion(Region.NA)
            .setPrivateKey("YOUR_PRIVATE_KEY")
            .setEnvironment(Environment.SANDBOX)
            .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");

        WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
        AmazonPayResponse response = null;
        String chargePermissionId = "S01-5105180-3221187";

        JSONObject payload = new JSONObject();
        JSONObject merchantMetadata = new JSONObject();
        merchantMetadata.put("merchantReferenceId", "32-41-323141");
        merchantMetadata.put("merchantStoreName", "AmazonTestStoreName");
        merchantMetadata.put("noteToBuyer", "merchantNoteForBuyer");
        merchantMetadata.put("customInformation", "This is custom information");
        payload.put("merchantMetadata", merchantMetadata);

        JSONObject recurringMetadata = new JSONObject();

        JSONObject frequency = new JSONObject();
        frequency.put("unit","Month");
        frequency.put("value","1");
        recurringMetadata.put("frequency", frequency);

        JSONObject amount = new JSONObject();
        amount.put("amount","14");
        amount.put("currencyCode","USD");
        recurringMetadata.put("amount", amount);

        payload.put("recurringMetadata", recurringMetadata);

        response = webstoreClient.updateChargePermission(chargePermissionId, payload);
    } catch (AmazonPayClientException e) {
        e.printStackTrace();
    }
}

const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const uuidv4 = require('uuid/v4');

const config = {
    publicKeyId: 'YOUR_PUBLIC_KEY_ID',
    privateKey: fs.readFileSync('tst/private.pem'),
    region: 'us',
    sandbox: true,
    algorithm: 'AMZN-PAY-RSASSA-PSS-V2' 
};    
                
const payload = {
  merchantMetadata: {
      merchantReferenceId: "123-77-876",
      merchantStoreName: "AmazonTestStoreFront",
      noteToBuyer: "merchantNoteForBuyer",
      customInformation: "This is custom information"
  },
  recurringMetadata: {
      frequency: {
          unit: "Month",
          value: "1"
      },
      amount: {
          amount: "14",
          currencyCode: "USD"
      }
  }
}
                        
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateChargePermission('S01-5105180-3221187',payload);

response.then(function (result) {
    console.log(result.data);
}).catch(err => {
    console.log(err);
});

Response

{
    "chargePermissionId": "S01-5105180-3221187",
    "chargePermissionReferenceId": null,
    "chargePermissionType": "Recurring",   
    "recurringMetadata": {
        "frequency": {
            "unit": "Month",
            "value": "1" 
        },
        "amount": {
            "amount": "14",
            "currencyCode": "USD"
        }
    },
    "buyer": {
        "buyerId": "buyerId",
        "name": "name-1",
        "email": "name@amazon.com",
        "phoneNumber": "800-000-0000",
        "primeMembershipTypes": null
    },
    "releaseEnvironment": "Live",
    "shippingAddress":{  // Null for PayOnly product type
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "billingAddress": {  
        "name": "Work",
        "addressLine1": "440 Terry Ave",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Seattle",
        "county": "King",
        "district": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98121",
        "countryCode": "US",
        "phoneNumber": "800-000-0000"
    },
    "paymentPreferences": [
    {
        "paymentDescriptor": null
    }],
    "statusDetails": {
        "state": "Chargeable",
        "reasons": null,
        "lastUpdatedTimestamp": "20190714T155300Z"
    },
    "creationTimestamp": "20190714T155300Z",
    "expirationTimestamp": "20190715T155300Z",
    "merchantMetadata": {
        "merchantReferenceId": "123-77-876", 
        "merchantStoreName": "AmazonTestStoreFront",
        "noteToBuyer": "merchantNoteForBuyer",
        "customInformation": "This is custom information"  
    },
    "platformId": "SPId",
    "limits": {
        "amountLimit": {
            "amount": "14.00",
            "currencyCode": "USD"
        },
        "amountBalance": {
            "amount": "14.00",
            "currencyCode": "USD"
        }
    },
    "presentmentCurrency": "USD"
}