Introduction

A transaction recording policy enables monetization to capture transaction parameters and custom attributes. Monetization needs this information to perform its monetization processing such as applying rate plans.

For example, if you set up a revenue share rate plan, a percentage of the revenue generated from each transaction involving your monetized API product is shared with the developer of the app issuing the request. The revenue share is based on the net or gross price of the transaction (you specify which one), that is, a percentage of the gross or net price of each transaction is used to determine the revenue share. Because of this, monetization needs to know the gross or net price of a transaction, as applicable. It gets the gross or net price from settings you make in the transaction recording policy.

Here is another example. If you set up a rate card plan, where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction. Monetization needs to know what the custom attribute is and where to find it. So you need to specify the custom attribute in the transaction recording policy.

Toolbox

You can create a transaction recording policy using the management UI or the management API (not the monetization API).

If you use the UI, you create a transaction recording policy using the Products selection in the Publish tab.

If you use the API, you create a transaction recording policy by adding it as an attribute of an API product.

Creating a transaction recording policy using the API can be complex. Because of this, it is recommended that you use the UI to create a transaction recording policy.

In addition to specifying transaction attributes in the transaction recording policy, you can specify transaction success criteria — to determine when a transaction is successful (for charging purposes). You can also specify custom attributes for an API product (on which you base rate plan charges). You can specify these in the UI or by using the management API (not the monetization API).

Creating a transaction recording policy in the UI

  1. On the Publish tab, select Products.

    This opens the Products page.

  2. Click + Transaction Recording Policy in the row for the applicable API product.

    This opens the New Transaction Recording Policy window.

  3. Enter information in the New Transaction Recording Policy window, as applicable.

    The window displays the following sections:

    • Transaction attributes
    • Custom Attributes
    • Link Resources with Unique Transaction ID
    • Refunds
    • XML Namespaces

Transaction Attributes

In this section, you select transaction-related attributes for inclusion in the transaction recording policy. Each of these attributes is then stored in the transaction log, which you can query.

For each transaction attribute that you include in the policy, you need to specify a resource for the transaction, a location where the transaction attribute is provided, and an attribute value. You also need to specify an expression based on the value of the Status attribute for determining when the transaction is successful (for charging purposes). Transactions that are not successful (that is, they do meet the criteria in the Success expression) are recorded, but rate plans are not applied to them.

 

The transaction attributes are as follows:

Attribute Description
Status

This attribute is required. The status of the transaction.

Gross price

This attribute is pertinent only for rate plans that use the revenue share model. For those rate plans, either Gross Price or Net Price is mandatory. The gross price for a transaction. For revenue share plans, you need to record either the Gross Price attribute or the Net Price attribute. Which attribute is required depends on the basis of the revenue share. For example, you can set up a revenue share rate plan that is based on the gross price of a transaction. In that case, the Gross Price field is required..

Net price

This attribute is pertinent only for rate plans that use the revenue share model. For those rate plans, either Gross Price or Net Price is mandatory. The net price for a transaction. For revenue share plans, you need to record either the Net Price field or the Gross Price field. Which field is required depends on the basis of the revenue share. For example, you can set up a revenue share rate plan that is based on the net price of a transaction. In that case, the Net Price field is required.

Currency

This attribute is required for rate plans that use the revenue share model. The type of currency that applies to the transaction.

Error Code

Optional. An error code associated with the transaction. It provides further information about a failed transaction.

Item Description

Optional. A description of the transaction.

Tax

Optional. This attribute is relevant only for revenue sharing models and only if the tax amount is captured in the API calls. The value is the tax amount on the purchase, that is the net price plus tax (that is, the gross price).

Resources: For each transaction attribute that you include in the policy, select one or more URI suffixes (that is, the URI fragment following the base path) of the API resources accessed by the transaction. The suffix includes a pattern variable that is enclosed in curly braces. The pattern variable is evaluated by API Services at runtime. For example, the following URI suffix includes the pattern variable {id}.

/reserve/{id}**

In this case, API Services evaluates the URI suffix of the resource as /reserve followed by any sub-directory that begins with an ID defined by the API provider.

Location: For each transaction attribute that you include in the policy, you need to select the location in the response where the attribute is specified. Choose one of the following locations:

  • Header
  • JSON body
  • XML body
  • XML and JSON body
  • Flow variable

Value: For each transaction attribute that you include in the policy, you need to specify an attribute value. This corresponds to the field, parameter, or content element that provides the attribute in the location that you specified. For example, for the Status attribute, you might select Response: Header as the location and enter a Value of status.

You can specify more than one value. For example, suppose there's an alternate response header element that can be specified for the Status value (say it's called trans_status). In that case, you want monetization to examine both the status and trans_status response header elements for the Status value. To add a value to an existing value entry, click + in the Value field.

Transaction Success Criteria: Use this field to specify an expression based on the value of the Status attribute for determining when the transaction is successful (for charging purposes). Transactions that are not successful (that is, they do meet the criteria in the expression) are recorded, but rate plans are not applied to them.

For example, you might specify an expression like this: txProviderStatus == 'success'

Custom Attributes

In this section, you select custom attributes for inclusion in the transaction recording policy. For example, if you set up a rate card plan, where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction. You then need to include that custom attribute in the transaction recording policy.

Custom attributes are attributes of an API product. They are added to an API product using the management API (and not through monetization). See Specifying custom attributes using the API.

Each of these attributes is stored in the transaction log, which you can query. They are also displayed when you create a rate plan (so that you can choose one or more of these attributes on which to base your rate for the plan).

For each custom attribute that you include in the policy, you need to specify a name, a resource for the transaction, a location where the custom attribute is provided, and an attribute value.

 

Name: Enter a name that describes the custom attribute. If the rate plan is based on a custom attribute, this name is displayed to the user in the rate plan details. For example, if the custom attribute captures duration, then you should name the attribute duration. The actual units for the custom attribute (such as hours, minutes, or seconds) are set in the rating unit field when you create a custom attribute rate plan (see Specify rate card with custom attribute details for details).

One of the custom attributes is specifically reserved for user-based limits (where the User limit condition is a specific user or "any" — see Set limits for further details about the User limit condition). To implement this limit, you must ensure that the name of the custom attribute is set to user (all lowercase).

Resource: For each custom attribute that you include in the policy, select one or more URI suffixes (that is, the URI fragment following the base path) of an API resource accessed in the transaction. The available resources are the same as for transaction attributes.

Location: For each custom attribute that you include in the policy, you need to select the location in the response where the attribute is specified. The available locations are the same as for transaction attributes.

Value: For each custom attribute that you include in the policy, you need to specify a value for the custom attribute. Each value that you specify corresponds to a field, parameter, or content element that provides the custom attribute in the location that you specified. For example, suppose you include a custom attribute named Content Length, and select Response: Header as the location. Suppose too that the Content Length value is provided in the HTTP Content-Length field. In that case, specifyContent-Length as the value.

You can specify more than one value. To add a value to an existing value entry, click + in the Value field.

Link Resources with Unique Transaction ID

Some transactions are simple, involving an API call to one resource. However, other transactions can be more complex. For example, suppose a transaction for purchasing an in-app product in a mobile gaming app involves multiple resource calls:

  • A call to a reserve API that ensures that a prepaid user has enough credit to purchase the product and allocates ("reserves") the funds for the purchase.
  • A call to a charge API that deducts the funds from the prepaid user's account.

To process the entire transaction, monetization needs a way of linking the first resource (the call and response to and from the reserve API) with the second resource (the call and response to and from the charge API). To do this, it relies on information that you specify in the Link Resources with Unique Transaction ID section.

For each transaction, you specify a resource, attribute location, and attribute value that is linked with a corresponding resource, attribute location, and attribute value in the other transactions.

For example, suppose the reserve API call and the charge API call are linked as follows: a field named session_id in the response header from the reserve API corresponds to a response header named reference_id from the charge API. In this case, your entries in the Link Resources with Unique Transaction ID section might look like this:

Resource Location Value
reserve/{id}**

Response: Header

session_id
/charge/{id}**

Response: Header

reference_id

The Link Resources with Unique Transaction ID section is applicable only if your transaction is complex, involving multiple parts (each one of which is a transaction).

Refunds

This section is pertinent only for rate plans that use the revenue share model and only if your API supports automatic refunds. In this section, you specify attributes that monetization uses to process refunds. For example, suppose a user purchases a product from a mobile app that uses your monetized APIs. The transaction is monetized based on the shared revenue plan.

However, suppose the user is unsatisfied with the product and wants to return it. If the product is refunded using a call to your API that does the refund, monetization makes the necessary monetization adjustments. It does this based on information that you specify in the Refunds section of the transaction recording policy.

You need to specify the resource for the refund transaction. If the API product provides multiple resources, you can select only the resource that performs the refund.

For each transaction attribute that you include in the refund section, you need to specify a location where the transaction attribute is provided, and an attribute value. You also need to specify an expression based on the value of the Status attribute for determining whether the refund transaction is successful.

The refund transaction attributes are:

Attribute Description
Status

This attribute is required. The status of the refund transaction (either successful or failed).

Parent Transaction ID

This attribute is required. The ID of the transaction for which a refund is processed. For example, if a user purchases a product and then requests a refund, the Parent Transaction ID is the ID of the purchase transaction.

Currency

The type of currency that applies to the transaction.

Gross price

The gross price for a transaction. You need to record either the Gross Price attribute or the Net Price attribute. Which attribute is required depends on the basis of the revenue share. For example, you can set up a revenue share rate plan that is based on the gross price of a transaction. In that case, the Gross Price field is required.

Net price

The net price for a transaction. You need to record either the Net Price field or the Gross Price field. Which field is required depends on the basis of the revenue share. For example, you can set up a revenue share rate plan that is based on the net price of a transaction. In that case, the Net Price field is required.

Sub Org ID

If the API provider is a sub-organization, the ID of the sub-organization.

Tax

The tax applied to the transaction.

Location: For each refund transaction attribute that you include in the policy, you need to select the location in the response where the attribute is specified. Choose one of the following locations:

  • Header
  • JSON body
  • XML body
  • XML and JSON body
  • Flow Variable

Value: For each refund transaction attribute that you include in the policy, you need to specify a value for the custom attribute. Each value that you specify corresponds to a field, parameter, or content element that provides the refund transaction attribute in the location that you specified. For example, suppose you include a refund transaction attribute named Content Length, and select Response: Header as the location. Suppose too, that the Content Length value is provided in the HTTP Content-Length field. In that case, specify Content-Length as the value.

You can specify more than one value. To add a value to an existing value entry, click + in the Value field.

Refund Success Criteria: Use this field to specify an expression based on the value of the Status attribute for determining when the refund transaction is successful (for charging purposes). Refund transactions that are not successful (that is, they do meet the criteria in the expression) are recorded, but rate plans are not applied to them.

For example, you might specify an expression like this: txProviderStatus == 'success'

Editing a transaction recording policy in the UI

After a transaction recording policy has been saved, you can edit it, if necessary.

  1. In the Products page, click Transaction Recording Policy in the row for the pertinent API product.

    This opens the Transaction Recording Policy window.

  2. Click Edit. This opens the Edit Transaction Recording Policy window.

  3. Edit any of the fields in the Transaction Recording policy.
  4. Click Save to save the updates (or Cancel to cancel).

Creating a transaction recording policy using the API

You specify a transaction recording policy as an attribute of an API product. The value of the attribute identifies:

  • The URI suffix of the product resource to which the transaction recording policy is attached. The suffix includes a pattern variable that is enclosed in curly braces. The pattern variable is evaluated by API Services at runtime. For example, the following URI suffix includes the pattern variable {id}.
    /reserve/{id}**
    

    In this case, API Services evaluates the URI suffix of the resource as /reserve followed by any sub-directory that begins with an ID defined by the API provider.

  • The resource in the response to which it is attached. An API product can have multiple resources and each resource can have a transaction recording policy attached to a response from that resource.
  • An extract variable policy that enables the transaction recording policy to extract content from a response message for the transaction parameters you want to capture.

The transaction recording policy attribute value is specified as a string of attributes and values. Each attribute and value in the string needs to be escaped with escape characters. As a result, specifying the transaction recording policy can be quite complex. Because of this complexity, it is recommended that you use the UI to set up a transaction recording policy. See Creating a transaction recording policy in the UI.

You add the transaction recording policy attribute to an API product by issuing a PUT request to the management API https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/apiproducts/{apiproduct_Id} (and not to a monetization API).

Specifying transaction success criteria using the API

You can specify transaction success criteria for determining when a transaction is successful (for charging purposes). Transactions that are not successful (that is, they do meet the criteria in the expression) are recorded, but rate plans are not applied to them.

You specify the transaction success criteria as an attribute of an API product. Do this by issuing a PUT request to the management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (and not to the monetization  API).

For example, in the following request a transaction is successful if the value of txProviderStatus is success (the transaction success criteria-related specifications are highlighted).

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
	"apiResources": [
    	"/reserve/{id}**"    	
	],
	"approvalType": "auto",
	"attributes": [    	        	
    	{
        	"name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
        	"value": "txProviderStatus == 'success'"
    	}
	],
	"description": "Payment",
	"displayName": "Payment",
	"environments": [
    	"dev"
	],
	"name": "payment",
	"proxies": [],
	"scopes": [
    	""
	]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u myname:mypass

Specifying custom attributes using the API

You can specify custom attributes for an API product on which you base rate plan charges. For example, if you set up a rate card plan, where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction. When you create a rate plan, you can specify one or more custom attributes on which to base your rate for the plan. However, any specific product in a rate plan, can only have one custom attribute on which to base the rate for the plan.

You specify custom attributes as attributes of an API product. Do this by issuing a PUT request to the management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (and not to the monetization  API).

For each custom attribute that you add to an API product, you need to specify a name and an attribute value. The name must be in the form MINT_CUSTOM_ATTRIBUTE_{num}, where {num} is an integer.

One of the custom attributes values is reserved for user-based limits (where the user limit condition is a specific user or any — see Set limits for further details about limits). To implement this limit, you must ensure that the value of the custom attribute is set to user (all lowercase).

For example, the following request specifies three custom attributes. One of the custom attributes, MINT_CUSTOM_ATTRIBUTE_3 , will used for user-based limits.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
	"apiResources": [
    	"/reserve/{id}**",
    	"/charge/{id}**"
	],
	"approvalType": "auto",
	"attributes": [
    	{
        	"name": "MINT_CUSTOM_ATTRIBUTE_1",
        	"value": "test1"
    	},
    	{
        	"name": "MINT_CUSTOM_ATTRIBUTE_2",
        	"value": "test2"
    	},
    	{
        	"name": "MINT_CUSTOM_ATTRIBUTE_3",
        	"value": "user"
    	}
    	],
	"name": "payment",
	"proxies": [],
	"scopes": [
	   	""
	]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u myname:mypass

Get help

For help, see Apigee Customer Support.

Next steps

If you set up a revenue share plan and you want to display any restrictions in pricing to developers, you need to set up price points as described in Set price points . Otherwise, see Create rate plans and start creating rate plans.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)