New Sale Transaction With Ramped Products

Understand the required values and key considerations before you create a billing schedule for a new sale transaction with ramped products.

Considerations

Keep these important considerations in mind when you provide the details for new sale transactions with ramped products.

The BillingActionType__std value for any new sale transaction must be Add.
For new sale transactions with a ramped product, the RampIdentifier__std value is required.
If you don’t provide the TaxTreatmentId__std value, the BillingTreatmentId__std value, or the LegalEntityId__std value for the transaction, the default TaxTreatmentId, BillingTreatmentId, and LegalEntityId of your Salesforce org is considered. If your org doesn’t have any default values, an error occurs.
The billing schedules for transactions with the same RampIdentifier__std value are created for the same billing schedule group.
To understand the requirements for the various selling model types, see these resources.

JSON Example

This example includes the transaction data for a new sale transaction with ramped products and a TermDefined selling model.

1{
2  "Transaction": [
3    {
4      "id": "ter1",
5      "SellingModelType__std": "TermDefined",
6      "ParentTransactionId__std": "sample",
7      "TransactionId__std": "ter1",
8      "ProductName__std": "TermedQuarterlyProduct",
9      "StartDate__std": "2025-01-01",
10      "EndDate__std": "2026-12-31",
11      "PeriodBoundary__std": "DayOfPeriod",
12      "BillingDayOfMonth__std": 1,
13      "UnitPrice__std": 10,
14      "Quantity__std": 5,
15      "TotalPrice__std": 120,
16      "TaxTreatmentId__std": "1ttLT000000EV7DYAW",
17      "BillingTreatmentId__std": "1BTLT00000008yT4AQ",
18      "AccountId__std": "001LT00000dPVrlYAG",
19      "BillingProfileId__std": "001LT00000dPVrlYAG",
20      "BillingCity__std": "HYD",
21      "ShippingCity__std": "VSKP",
22      "BillingTermUnit__std": "Month",
23      "BillingActionType__std": "Add",
24      "CurrencyIsoCode__std": "USD",
25      "RampIdentifier__std": "ramp1"
26    },
27    {
28      "id": "ter2",
29      "SellingModelType__std": "TermDefined",
30      "ParentTransactionId__std": "sample",
31      "TransactionId__std": "ter2",
32      "ProductName__std": "TermedQuarterlyProduct",
33      "StartDate__std": "2025-01-01",
34      "EndDate__std": "2026-12-31",
35      "PeriodBoundary__std": "DayOfPeriod",
36      "BillingDayOfMonth__std": 1,
37      "UnitPrice__std": 10,
38      "Quantity__std": 5,
39      "TotalPrice__std": 120,
40      "TaxTreatmentId__std": "1ttLT000000EV7DYAW",
41      "BillingTreatmentId__std": "1BTLT00000008yT4AQ",
42      "AccountId__std": "001LT00000dPVrlYAG",
43      "BillingProfileId__std": "001LT00000dPVrlYAG",
44      "BillingCity__std": "HYD",
45      "ShippingCity__std": "VSKP",
46      "BillingTermUnit__std": "Month",
47      "BillingActionType__std": "Add",
48      "CurrencyIsoCode__std": "USD",
49      "RampIdentifier__std": "ramp1"
50    }
51  ]
52}

This example shows the request payload to create a billing schedule for a new sale transaction with ramped products and a TermDefined selling model.

1{
2  "transactionDetails": "{\"Transaction\":[{\"id\":\"ter1\",\"SellingModelType__std\":\"TermDefined\",\"ParentTransactionId__std\":\"sample\",\"TransactionId__std\":\"ter1\",\"ProductName__std\":\"TermedQuarterlyProduct\",\"StartDate__std\":\"2025-01-01\",\"EndDate__std\":\"2026-12-31\",\"PeriodBoundary__std\":\"DayOfPeriod\",\"BillingDayOfMonth__std\":1,\"UnitPrice__std\":10,\"Quantity__std\":5,\"TotalPrice__std\":120,\"TaxTreatmentId__std\":\"1ttLT000000EV7DYAW\",\"BillingTreatmentId__std\":\"1BTLT00000008yT4AQ\",\"AccountId__std\":\"001LT00000dPVrlYAG\",\"BillingProfileId__std\":\"001LT00000dPVrlYAG\",\"BillingCity__std\":\"HYD\",\"ShippingCity__std\":\"VSKP\",\"BillingTermUnit__std\":\"Month\",\"BillingActionType__std\":\"Add\",\"CurrencyIsoCode__std\":\"USD\",\"RampIdentifier__std\":\"ramp1\"},{\"id\":\"ter2\",\"SellingModelType__std\":\"TermDefined\",\"ParentTransactionId__std\":\"sample\",\"TransactionId__std\":\"ter2\",\"ProductName__std\":\"TermedQuarterlyProduct\",\"StartDate__std\":\"2025-01-01\",\"EndDate__std\":\"2026-12-31\",\"PeriodBoundary__std\":\"DayOfPeriod\",\"BillingDayOfMonth__std\":1,\"UnitPrice__std\":10,\"Quantity__std\":5,\"TotalPrice__std\":120,\"TaxTreatmentId__std\":\"1ttLT000000EV7DYAW\",\"BillingTreatmentId__std\":\"1BTLT00000008yT4AQ\",\"AccountId__std\":\"001LT00000dPVrlYAG\",\"BillingProfileId__std\":\"001LT00000dPVrlYAG\",\"BillingCity__std\":\"HYD\",\"ShippingCity__std\":\"VSKP\",\"BillingTermUnit__std\":\"Month\",\"BillingActionType__std\":\"Add\",\"CurrencyIsoCode__std\":\"USD\",\"RampIdentifier__std\":\"ramp1\"}]}",
3  "transactionContextDetails": {
4    "contextDefinitionName": "StandaloneBillingContext__stdctx",
5    "intraContextCustomMappingName": "CustomContextMapping",
6    "readContextMappingName": "TransactionMapping",
7    "saveContextMappingName": "BSGEntitiesMapping"
8  }
9}

When you’re creating a billing schedule for a new sale transaction with ramped products, make sure that you specify the mandatory values in the transactionDetails property value.

Name	Description	Mapped Field	Required or Optional
`ParentTransactionId__std`	The ID of the parent transaction record. For example, if the transaction is at a level similar to that of an Order Item record, the parent transaction will be at a level similar to that of an Order record.	If the transaction is a child Order or Quote record, the ReferenceEntityId field on the BillingScheduleobject is populated. For other sObject records or external records, the Reference field on the BillingSchedule object is populated.	Optional
`AccountId__std`	The ID of the Account record that’s related to the transaction.	BillingAccountId field on the BillingScheduleGroup object	Required
`BillingProfileId__std`	The ID of the billing profile (Billing Account record) that’s related to the transaction. See Billing Profile requirements.	BillingAccountId field on the BillingSchedule object	Optional
`BillingCity__std`	The city in the billing address of the transaction.	BillingCity field on the BillingScheduleGroup object	Any one of the billing address fields is required.
`ShippingCity__std`	The city in the shipping address of the transaction.	ShippingCity field on the BillingScheduleGroup object	Any one of the shipping address fields is required.
`SellingModelType__std`	The selling model type indicates whether the transaction is for a one-time product, a term-defined product, or an evergreen product. Specify `OneTime` as the SellingModelType for the transaction that’s related to a product that’s sold once.	BillingMethod on the BillingSchedule object is populated as OrderAmount.	Required
`TransactionId__std`	The ID of the transaction that you want to create a billing schedule for.	If the transaction is an OrderItem, OrderItemAdjustmentLineItem, OrderItemDetail, QuoteLineDetail, or QuoteLineItem record, the ReferenceEntityItemId field on the BillingScheduleobject is populated. For other sObject records or external records, the ReferenceItem field on the BillingSchedule object is populated.	Required
`ProductName__std`	The name of the product that’s related to the transaction that you want to create a billing schedule for.	ProductName field on the BillingScheduleGroup object	Either the ProductName or the ProductId is required
`PeriodBoundary__std`	The period boundary determines the start and end date of the billing period.	PeriodBoundary field on the BillingScheduleGroup object	Required for products with the `TermDefined` or `Evergreen` selling model types.
`BillingDayOfMonth__std`	The day of the month on which a recurring billing process is scheduled to occur for the transaction.	BillDayOfMonth field on the BillingScheduleGroup object	Required for products with the `TermDefined` or `Evergreen` selling model types.
`EndDate__std`	The end date of the transaction.	BillingScheduleEndDate field on the BillingSchedule object	Required for products with the `TermDefined` selling model type.
`StartDate__std`	The start date of the transaction.	BillingScheduleStartDate field on the BillingSchedule object	Required
`Quantity__std`	The quantity of the transaction.	Quantity field on the BillingSchedule object	Required
`TaxTreatmentId__std`	The ID of the tax treatment that’s used to calculate tax for the transaction. If you don’t specify a TaxTreatmentId, the org-default TaxTreatmentId is considered.	TaxTreatmentId field on the BillingScheduleGroup object	Required
`BillingTermUnit__std`	The unit of measurement of the billing term.	BillingTermUnit field on the BillingSchedule object	Required for products with the `TermDefined` or `Evergreen` selling model types.
`BillingTreatmentId__std`	The ID of the billing treatment that’s used to create the billing schedule for the transaction. If you don’t specify a BillingTreatmentId, the org-default BillingTreatmentId is considered.	BillingTreatmentId field on the BillingScheduleGroup object	Required
`CurrencyIsoCode__std`	The currency code of the transaction amount if your Salesforce org has multi-currency enabled.	CurrencyIsoCode field on the BillingScheduleGroup object	Required for Salesforce orgs with multiple currencies enabled.
`RampIdentifier__std`	When the transaction is part of a ramp deal, the RampIdentifier value is a unique identifier for that ramp. All the transactions with the same RampIdentifier value are grouped to have billing schedules for the same billing schedule group.	This value isn’t populated on any BillingSchedule or BillingScheduleGroup field.	Required
`BillingActionType__std`	The action that you want to perform for the transaction. Valid value is `Add`.	Category field on the BillingSchedule object is populated as Original.	Required
`UnitPrice__std`	The unit price of the transaction.	UnitPrice field on the BillingSchedule object	Either the UnitPrice or the NetUnitPrice value is required
`TotalPrice__std`	The total price of the transaction.	TotalAmount field on the BillingSchedule object	Required

Valid PeriodBoundary__std values:

AlignToCalendar
Anniversary
DayOfPeriod
LastDayOfPeriod

Valid BillingTermUnit__std values:

Month
Quarter
Semi-Annual
Year