Usage-Based Product Input

Understand the sample request structure to specify and manage usage-based products within a sales transaction.

JSON Example to Create a Quote Record With Default Rates and Default Grants

The example shows a sample request to creates these records with these updates.

Quote—Creates the main quote record with default rates and default grants.
Quote Line Item—Adds a product to the quote.
Rate Card Entry—Links default pricing from rate card. When NegotiatedRate property value is null, the rate card price is used.
Usage Grant—Allocates all default grants.

1{
2  "pricingPref": "system",
3  "configurationPref": {
4    "configurationMethod": "skip",
5    "configurationOptions": {
6      "validateProductCatalog": false,
7      "validateAmendRenewCancel": false,
8      "executeConfigurationRules": false,
9      "addDefaultConfiguration": false
10    }
11  },
12  "graph": {
13    "graphId": "graphId",
14    "records": [
15      {
16        "referenceId": "refQuote",
17        "record": {
18          "attributes": {
19            "type": "Quote",
20            "method": "POST"
21          },
22          "Name": "Q-2024-001",
23          "QuoteAccountId": "001xx000003DHP0AAO",
24          "OpportunityId": "006xx000004TmiGAAS",
25          "Status": "Draft",
26          "Pricebook2Id": "01sxx0000001SGEAA2"
27        }
28      },
29      {
30        "referenceId": "refQuoteLineItem",
31        "record": {
32          "attributes": {
33            "type": "QuoteLineItem",
34            "method": "POST"
35          },
36          "QuoteId": "@{refQuote.id}",
37          "Product2Id": "01txx0000001SGEAA2",
38          "StartDate": "2024-10-29",
39          "PeriodBoundary": "Anniversary",
40          "EndDate": "2027-03-01",
41          "PricebookEntryId": "01uxx0000001SGEAA2",
42          "UnitPrice": 100,
43          "Quantity": 1
44        }
45      },
46      {
47        "referenceId": "refRateCardEntry",
48        "record": {
49          "attributes": {
50            "type": "QuoteLineRateCardEntry",
51            "method": "POST"
52          },
53          "RateCardEntryId": "1CJxx0000004CXEGA2",
54          "NegotiatedRate": null,
55          "QuoteLineItemId": "@{refQuoteLineItem.id}"
56        }
57      }
58    ]
59  }
60}

JSON Example to Specify Negotiated Grants

This example shows a sample response to create a QuotLineItmUseRsrcGrant record that links a quote line item to a product usage grant for usage-based products. This request performs these updates.

Associates a usage grant with a quote line item.
Allocates a quantity of usage resources.
Applies a usage policy that defines how the resources can be consumed.
Links to a base product usage grant that defines the grant structure.

1{
2  "pricingPref": "system",
3  "configurationPref": {
4    "configurationMethod": "skip",
5    "configurationOptions": {
6      "validateProductCatalog": false,
7      "validateAmendRenewCancel": false,
8      "executeConfigurationRules": false,
9      "addDefaultConfiguration": false
10    }
11  },
12  "graph": {
13    "graphId": "graphId",
14    "records": [
15      {
16        "referenceId": "ref1CJxx0000004CXGGA2",
17        "record": {
18          "attributes": {
19            "type": "QuotLineItmUseRsrcGrant",
20            "method": "POST"
21          },
22          "GrantQuantity": 4,
23          "ProductUsageResourcePolicyId": "7Suxx0000004C92CAE",
24          "QuoteLineItemId": "0QLxx0000004CnMGAU",
25          "ProductUsageGrantId": "1BXxx0000004C92GAE"
26        }
27      }
28    ]
29  }
30}

This example shows a sample response to update the previously created QuotLineItmUseRsrcGrant record with additional units, which is specified by using the GrantQuantity property. The quote line item now has 97 units of usage resource allocation.

1{
2  "pricingPref": "system",
3  "configurationPref": {
4    "configurationMethod": "skip",
5    "configurationOptions": {
6      "validateProductCatalog": false,
7      "validateAmendRenewCancel": false,
8      "executeConfigurationRules": false,
9      "addDefaultConfiguration": false
10    }
11  },
12  "graph": {
13    "graphId": "graphId",
14    "records": [
15      {
16        "referenceId": "ref1X6xx000000003GCAQ",
17        "record": {
18          "attributes": {
19            "method": "PATCH",
20            "type": "QuotLineItmUseRsrcGrant",
21            "id": "1X6xx000000003GCAQ"
22          },
23          "GrantQuantity": 97
24        }
25      }
26    ]
27  }
28}

JSON Example to Specify Tiered Pricing and Usage Grants

This example shows a sample request to update an existing quote with tiered pricing and usage grants. This request sets up a multi-tier rate structure and updates a usage grant quantity along with these additional updates.

Creates a base rate card entry with a negotiated rate of 10. Sets the base price for the quote line item.
Creates a second rate card entry for tiered pricing without any negotiated rate. The default rate card is used. This rate card entry is the base for tier adjustments.
Creates a tier adjustment for quantities 0 through 50 and adds $5 adjustment to the base rate.
Creates a tier adjustment for quantities 50 through 100 and adds an adjustment of $10.
Updates an existing usage resource grant record to set grant quantity to 150 units.

For example, if an order is placed for 75 units, the base rate is $10. As tier 2 is applicable for this order, an adjustment of $10 is applicable. The final price per unit is $20 with a total of $1500 for 75 units.

1{
2  "pricingPref": "system",
3  "configurationPref": {
4    "configurationMethod": "skip",
5    "configurationOptions": {
6      "validateProductCatalog": false,
7      "validateAmendRenewCancel": false,
8      "executeConfigurationRules": false,
9      "addDefaultConfiguration": false
10    }
11  },
12  "graph": {
13    "graphId": "graphId",
14    "records": [
15      {
16        "referenceId": "refLineItemParent",
17        "record": {
18          "attributes": {
19            "type": "Quote",
20            "method": "PATCH",
21            "id": "0Q0xx0000004CXEGA2"
22          }
23        }
24      },
25      {
26        "referenceId": "ref1",
27        "record": {
28          "attributes": {
29            "type": "QuoteLineRateCardEntry",
30            "method": "POST"
31          },
32          "RateCardEntryId": "1CJxx0000004CXEGA2",
33          "NegotiatedRate": 10,
34          "QuoteLineItemId": "0QLxx0000004Eh6GAE"
35        }
36      },
37      {
38        "referenceId": "refTierRateCardEntry0",
39        "record": {
40          "attributes": {
41            "type": "QuoteLineRateCardEntry",
42            "method": "POST"
43          },
44          "RateCardEntryId": "1CJxx0000004CXFGA2",
45          "QuoteLineItemId": "0QLxx0000004Eh6GAE"
46        }
47      },
48      {
49        "referenceId": "refTier0",
50        "record": {
51          "attributes": {
52            "type": "QuoteLineRateAdjustment",
53            "method": "POST"
54          },
55          "Name": "Tier 1",
56          "AdjustmentType": "Amount",
57          "AdjustmentValue": 5,
58          "LowerBound": 0,
59          "UpperBound": 50,
60          "QuoteLineRateCardEntryId": "@{refTierRateCardEntry0.id}"
61        }
62      },
63      {
64        "referenceId": "refTier1",
65        "record": {
66          "attributes": {
67            "type": "QuoteLineRateAdjustment",
68            "method": "POST"
69          },
70          "Name": "Tier 2",
71          "AdjustmentType": "Amount",
72          "AdjustmentValue": 10,
73          "LowerBound": 50,
74          "UpperBound": 100,
75          "QuoteLineRateCardEntryId": "@{refTierRateCardEntry0.id}"
76        }
77      },
78      {
79        "referenceId": "refTier2",
80        "record": {
81          "attributes": {
82            "type": "QuoteLineRateAdjustment",
83            "method": "POST"
84          },
85          "Name": "Tier 3",
86          "AdjustmentType": "Amount",
87          "AdjustmentValue": 15,
88          "LowerBound": 100,
89          "UpperBound": 150,
90          "QuoteLineRateCardEntryId": "@{refTierRateCardEntry0.id}"
91        }
92      },
93      {
94        "referenceId": "refGt2xzdUP",
95        "record": {
96          "attributes": {
97            "type": "QuotLineItmUseRsrcGrant",
98            "method": "PATCH",
99            "id": "1X6xx000000003GCAQ"
100          },
101          "GrantQuantity": 150
102        }
103      }
104    ]
105  }
106}