Billing Checkout (POST)

Create a unified checkout transaction that generates billing schedules, an invoice, and an optional payment in a single request.

Use this API to process a checkout transaction for invoicing and payment. Specify account or customer details, line items, billing information, and payment details. You can also preview the invoice without committing the checkout transaction.

Special Access Rules

You need the Billing Checkout access permission to use this API.

Resource

1/commerce/invoicing/invoices/collection/actions/checkout

Resource Example

1https://{yourInstance}.salesforce.com/services/data/v68.0/commerce/invoicing/invoices/collection/actions/checkout

Available Version

68.0

HTTP Methods

POST

Request Body for POST

JSON Example

1{
2  "previewInvoice": false,
3  "shouldCapturePayment": true,
4  "isPartialPaymentAllowed": false,
5  "accountId": "001xx0000004C90",
6  "invoiceDate": "2026-09-01",
7  "invoiceTargetDate": "2026-12-31",
8  "currencyIsoCode": "USD",
9  "amount": 1400.00,
10  "billingContact": {
11    "firstName": "Alex",
12    "lastName": "Rivera",
13    "email": "alex.rivera@example.com",
14    "phone": "+1-415-555-0100"
15  },
16  "billingAddress": {
17    "street": "415 Mission St",
18    "city": "San Francisco",
19    "state": "California",
20    "stateCode": "CA",
21    "country": "United States",
22    "countryCode": "US",
23    "postalCode": "94105"
24  },
25  "shippingAddress": {
26    "street": "415 Mission St",
27    "city": "San Francisco",
28    "stateCode": "CA",
29    "countryCode": "US",
30    "postalCode": "94105"
31  },
32  "paymentDetails": {
33    "paymentGatewayId": "0cgxx0000004C91",
34    "idempotencyKey": "checkout-2026-09-01-abc123",
35    "savedPaymentMethodDetails": {
36      "merchantAccount": "0dmxx0000004C92",
37      "gatewayToken": "tok_1PabcXYZ",
38      "gatewayReference": "cus_ORef123",
39      "type": "Card",
40      "name": "Acme Corp Visa"
41    }
42  },
43  "lineItems": [
44    {
45      "productName": "Platform Subscription",
46      "transactionId": "TXN-PLATFORM-001",
47      "quantity": 10,
48      "unitPrice": 100.00,
49      "netUnitPrice": 100.00,
50      "lineTotal": 1000.00,
51      "startDate": "2026-09-01",
52      "endDate": "2027-08-31",
53      "sellingModelType": "TermDefined",
54      "periodBoundary": "DayOfPeriod",
55      "billingDayOfMonth": 1,
56      "billingTermUnit": "Month",
57      "billingTerm": 12,
58      "taxTreatmentId": "0cXxx0000004C94",
59      "billingTreatmentId": "0cYxx0000004C95",
60      "bundleProductDetails": [
61        {
62          "productName": "Premium Support Add-on",
63          "associatedTransactionPricing": "IncludedInBundlePrice",
64          "quantity": 10,
65          "unitPrice": 200.00,
66          "netUnitPrice": 200.00,
67          "lineTotal": 200.00,
68          "sellingModelType": "TermDefined",
69          "periodBoundary": "DayOfPeriod",
70          "billingDayOfMonth": 1,
71          "billingTermUnit": "Month",
72          "billingTerm": 12,
73          "taxTreatmentId": "0cXxx0000004C94",
74          "billingTreatmentId": "0cYxx0000004C95"
75        }
76      ],
77      "ramps": [
78        {
79          "productId": "01txx0000004C93",
80          "startDate": "2026-09-01",
81          "endDate": "2027-02-28",
82          "quantity": 10,
83          "unitPrice": 100.00,
84          "netUnitPrice": 100.00,
85          "lineTotal": 500.00,
86          "sellingModelType": "TermDefined",
87          "periodBoundary": "DayOfPeriod",
88          "billingDayOfMonth": 1,
89          "billingTermUnit": "Month",
90          "billingTerm": 6
91        },
92        {
93          "productId": "01txx0000004C93",
94          "startDate": "2027-03-01",
95          "endDate": "2027-08-31",
96          "quantity": 10,
97          "unitPrice": 100.00,
98          "netUnitPrice": 100.00,
99          "lineTotal": 500.00,
100          "sellingModelType": "TermDefined",
101          "periodBoundary": "DayOfPeriod",
102          "billingDayOfMonth": 1,
103          "billingTermUnit": "Month",
104          "billingTerm": 6
105        }
106      ]
107    },
108    {
109      "productName": "Onboarding Fee",
110      "quantity": 1,
111      "unitPrice": 200.00,
112      "netUnitPrice": 200.00,
113      "lineTotal": 200.00,
114      "sellingModelType": "OneTime",
115      "billingTermUnit": "OneTime",
116      "billingTerm": 1
117    }
118  ]
119}

JSON Example — Using an Existing Payment Record

This example passes paymentId directly for an existing payment record, instead of paymentDetails.

1{
2  "accountId": "001SG00001QDo2kYAD",
3  "currencyIsoCode": "USD",
4  "amount": 60,
5  "previewInvoice": false,
6  "shouldCapturePayment": false,
7  "paymentId": "0aQSG0000020WoL2AU",
8  "lineItems": [
9    {
10      "productId": "01txx0000004C91",
11      "quantity": 1,
12      "unitPrice": 60.00,
13      "netUnitPrice": 60.00,
14      "lineTotal": 60.00
15    }
16  ]
17}

Properties

Name	Type	Description	Required or Optional	Available Version
`accountId`	String	ID of the account placing the order. Use this or `customerDetails`.	Optional	68.0
`amount`	Double	Total amount to charge for this checkout transaction.	Required	68.0
`billingAddress`	Address Input	Customer’s billing address. Use this or `billingProfileId`.	Optional	68.0
`billingContact`	Billing Contact Input	Billing customer details when `billingProfileId` isn’t provided. Creates the contact if it doesn’t exist.	Optional	68.0
`billingProfileId`	String	ID of an existing billing profile. Use this or `billingAddress`.	Optional	68.0
`currencyIsoCode`	String	The currency code of the transaction amount if your Salesforce org has multi-currency enabled.	Required	68.0
`customerDetails`	Billing Checkout Customer Details Input	Customer details used to create a customer when `accountId` isn’t provided.	Optional	68.0
`invoiceDate`	String	Date that appears on the generated invoice (YYYY-MM-DD). Defaults to the transaction date.	Optional	68.0
`invoiceTargetDate`	String	End date for the billing period to include on this invoice (YYYY-MM-DD). Creates a targeted invoice.	Optional	68.0
`isPartialPaymentAllowed`	Boolean	Indicates whether partial payment is allowed for this payment context (`true`) or not (`false`). The default value is `false`.	Optional	68.0
`lineItems`	Billing Checkout Line Item Input[]	Array of products being purchased.	Required	68.0
`paymentDetails`	Billing Checkout Payment Details Input	Raw payment details used to tokenize a new card or bank account. Use this or `paymentMethodId`.	Optional	68.0
`paymentId`	String	ID of an existing payment record to associate with this checkout transaction. Not allowed when `shouldCapturePayment` is `true`, and not allowed together with `amount`.	Optional	68.0
`paymentMethodId`	String	ID of a saved payment method. Use this or `paymentDetails`.	Optional	68.0
`previewInvoice`	Boolean	If `true`, returns a preview of the invoice without committing the checkout transaction.	Optional	68.0
`shippingAddress`	Address Input	Customer’s shipping address.	Optional	68.0
`shouldCapturePayment`	Boolean	If `true`, captures the payment as part of the checkout transaction.	Optional	68.0

Response Body for POST

Billing Checkout