Invoice Ingestion (POST)

Ingest or generate an invoice from an internal or external billing transaction data.

Create invoices from any external or internal transaction. For example, create invoices by using external orders, policies, quotes, or internal data, such as assets or quotes.

You can also perform these additional tasks.

Ingest invoices from any external system into Billing to manage invoice operations such as issuing credits against an invoice or voiding an invoice.
Generate invoices from debit memos from API version 66.0 and later.

Keep these considerations in mind when you use this API.

If the Convert Negative Invoice Lines to Credit Memo Lines feature isn’t enabled, use the Negative Invoice Lines to Credit Conversion API to create a credit memo against an ingested negative invoice line.
Use the Apply Credit Action to apply a credit memo to an invoice.
To ingest legacy invoices, create at least one invoice line.
To generate invoices from debit memos, specify the debit memo ID as the referenceEntityId property value in the request body of this API. Make sure that the debit memo is in Posted status and is ready for invoice generation. The invoice is generated in Draft status.

Resource

1/commerce/invoicing/invoices/collection/actions/ingest

Resource Example

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

Available Version

63.0

HTTP Methods

POST

Request Body for POST

JSON Example to Ingest a Draft Invoice With a Tax Callout

1{
2  "invoices": [
3    {
4      "shouldCalculateTax": true,
5      "taxCalculationStatus": "Estimated",
6      "graph": {
7        "graphId": "CreateInvoice",
8        "records": [
9          {
10            "referenceId": "refAccount",
11            "record": {
12              "attributes": {
13                "type": "Account",
14                "method": "GET",
15                "id": "ExternalId__c/123"
16              }
17            }
18          },
19          {
20            "referenceId": "refContact",
21            "record": {
22              "attributes": {
23                "type": "Contact",
24                "method": "GET",
25                "id": "ExternalId__c/123"
26              }
27            }
28          },
29          {
30            "referenceId": "refInvoice",
31            "record": {
32              "attributes": {
33                "type": "Invoice",
34                "method": "POST"
35              },
36              "billingAccountId": "@{refAccount.Id}",
37              "billToContactId": "@{refContact.Id}",
38              "paymentTermId": "2OXxx0000004CFUGA2",
39              "referenceEntityId": "801xx000003GeQQAA0",
40              "status": "Draft",
41              "invoiceDate": "2024-12-19",
42              "currencyIsoCode": "USD",
43              "dueDate": "2024-12-19",
44              "invoiceNumber": "DOC-10",
45              "description": "Sample Invoice",
46              "uniqueIdentifier": "5873af8f-f007-4aa0-9e3d-53a08c3f59de"
47            }
48          },
49          {
50            "referenceId": "refBillingAddress",
51            "record": {
52              "attributes": {
53                "type": "InvoiceAddressGroup",
54                "method": "POST"
55              },
56              "street": "123 Main St",
57              "city": "NewYork",
58              "postalCode": "10001",
59              "state": "New York",
60              "country": "US",
61              "longitude": "123.456",
62              "latitude": "78.910",
63              "invoiceId": "@{refInvoice.id}"
64            }
65          },
66          {
67            "referenceId": "refShippingAddress",
68            "record": {
69              "attributes": {
70                "type": "InvoiceAddressGroup",
71                "method": "POST"
72              },
73              "street": "123 Main St",
74              "city": "NewYork",
75              "postalCode": "10001",
76              "state": "New York",
77              "country": "US",
78              "longitude": "123.456",
79              "latitude": "78.910",
80              "invoiceId": "@{refInvoice.id}"
81            }
82          },
83          {
84            "referenceId": "refShipFromAddress",
85            "record": {
86              "attributes": {
87                "type": "InvoiceAddressGroup",
88                "method": "POST"
89              },
90              "street": "1 Market Street",
91              "city": "San Francisco",
92              "postalCode": "94105",
93              "state": "CA",
94              "country": "US",
95              "longitude": "123.456",
96              "latitude": "78.910",
97              "invoiceId": "@{refInvoice.id}"
98            }
99          },
100          {
101            "referenceId": "refInvoiceLine1",
102            "record": {
103              "attributes": {
104                "type": "InvoiceLine",
105                "method": "POST"
106              },
107              "name": "productName1",
108              "product2Id": "01txx0000006ic4AAA",
109              "invoiceLineStartDate": "2024-11-10",
110              "invoiceLineEndDate": "2024-11-13",
111              "quantity": "10",
112              "unitPrice": "10",
113              "chargeAmount": "100",
114              "invoiceId": "@{refInvoice.id}",
115              "referenceEntityItemId": "802xx000001neB9AAI",
116              "billingAddressId": "@{refBillingAddress.id}",
117              "shippingAddressId": "@{refShippingAddress.id}",
118              "shipFromAddressId": "@{refShipFromAddress.id}",
119              "taxTreatmentId": "1ttxx0000000BOTAA2",
120              "legalEntityId": "0fwxx0000000001AAA",
121              "legalEntityAccountingPeriodId": "1HLxx0000004C92GAE"
122            }
123          },
124          {
125            "referenceId": "refInvoiceLine2",
126            "record": {
127              "attributes": {
128                "type": "InvoiceLine",
129                "method": "POST"
130              },
131              "name": "productName2",
132              "product2Id": "01txx0000006ic4AAA",
133              "invoiceLineStartDate": "2024-11-10",
134              "invoiceLineEndDate": "2024-11-15",
135              "quantity": "10",
136              "unitPrice": "10",
137              "chargeAmount": "100",
138              "invoiceId": "@{refInvoice.id}",
139              "referenceEntityItemId": "802xx000001neB9AAI",
140              "billingAddressId": "@{refBillingAddress.id}",
141              "shippingAddressId": "@{refShippingAddress.id}",
142              "shipFromAddressId": "@{refShipFromAddress.id}",
143              "taxTreatmentId": "1ttxx00000001DpAAI",
144              "legalEntityId": "0fwxx0000000001AAA",
145              "legalEntityAccountingPeriodId": "1HLxx0000004C92GAE"
146            }
147          },
148          {
149            "referenceId": "refInvoiceLineTax",
150            "record": {
151              "attributes": {
152                "type": "InvoiceLineTax",
153                "method": "POST"
154              },
155              "taxAmount": 7.25,
156              "taxCode": "CA-94121",
157              "taxName": "CALIFORNIA",
158              "taxRate": 0.25,
159              "taxEffectiveDate": "2024-11-10",
160              "taxDocumentNumber": "123",
161              "taxExemptAmount": 0,
162              "taxTransactionNumber": "kl",
163              "description": "Associated tax line.",
164              "invoiceLineId": "@{refInvoiceLine1.id}"
165            }
166          },
167          {
168            "referenceId": "refInvoiceLineTax1",
169            "record": {
170              "attributes": {
171                "type": "InvoiceLineTax",
172                "method": "POST"
173              },
174              "taxAmount": "10",
175              "taxCode": "CA-94121",
176              "taxName": "CALIFORNIA",
177              "taxRate": 0.25,
178              "taxEffectiveDate": "2024-11-10",
179              "taxDocumentNumber": "123",
180              "taxExemptAmount": 0,
181              "taxTransactionNumber": "125",
182              "invoiceLineId": "@{refInvoiceLine2.id}",
183              "description": "Associated tax line."
184            }
185          }
186        ]
187      }
188    }
189  ]
190}

JSON Example to Ingest a Draft Invoice Without a Tax Callout

1{
2  "invoices": [
3    {
4      "taxCalculationStatus": "Estimated",
5      "graph": {
6        "graphId": "123",
7        "records": [
8          {
9            "referenceId": "refAccount",
10            "record": {
11              "attributes": {
12                "type": "Account",
13                "method": "GET",
14                "id": "TestExternalId__c/123"
15              }
16            }
17          },
18          {
19            "referenceId": "refInvoice",
20            "record": {
21              "attributes": {
22                "type": "Invoice",
23                "method": "POST"
24              },
25              "billingAccountId": "@{refAccount.Id}",
26              "billToContactId": "003xx000004Wk8qAAC",
27              "paymentTermId": "2OXxx0000004CFUGA2",
28              "referenceEntityId": "801xx000003GeQQAA0",
29              "status": "Draft",
30              "invoiceDate": "2024-12-19",
31              "currencyIsoCode": "USD",
32              "dueDate": "2024-12-19",
33              "invoiceNumber": "DOC-10",
34              "description": "testInvoice",
35              "uniqueIdentifier": "c76011a1-e113-49d9-9c54-3b5c68950ada"
36            }
37          },
38          {
39            "referenceId": "refBillingAddress",
40            "record": {
41              "attributes": {
42                "type": "InvoiceAddressGroup",
43                "method": "POST"
44              },
45              "street": "123 Main St",
46              "city": "NewYork",
47              "postalCode": "10001",
48              "state": "New York",
49              "country": "US",
50              "longitude": "123.456",
51              "latitude": "78.910",
52              "invoiceId": "@{refInvoice.id}"
53            }
54          },
55          {
56            "referenceId": "refShippingAddress",
57            "record": {
58              "attributes": {
59                "type": "InvoiceAddressGroup",
60                "method": "POST"
61              },
62              "street": "123 Main St",
63              "city": "NewYork",
64              "postalCode": "10001",
65              "state": "New York",
66              "country": "US",
67              "longitude": "123.456",
68              "latitude": "78.910",
69              "invoiceId": "@{refInvoice.id}"
70            }
71          },
72          {
73            "referenceId": "refShipFromAddress",
74            "record": {
75              "attributes": {
76                "type": "InvoiceAddressGroup",
77                "method": "POST"
78              },
79              "street": "1 Market Street",
80              "city": "San Francisco",
81              "postalCode": "94105",
82              "state": "CA",
83              "country": "US",
84              "longitude": "123.456",
85              "latitude": "78.910",
86              "invoiceId": "@{refInvoice.id}"
87            }
88          },
89          {
90            "referenceId": "refInvoiceLine1",
91            "record": {
92              "attributes": {
93                "type": "InvoiceLine",
94                "method": "POST"
95              },
96              "name": "productName1",
97              "product2Id": "01txx0000006ic4AAA",
98              "invoiceLineStartDate": "2024-11-10",
99              "invoiceLineEndDate": "2024-11-13",
100              "quantity": "10",
101              "unitPrice": "10",
102              "chargeAmount": "100",
103              "invoiceId": "@{refInvoice.id}",
104              "referenceEntityItemId": "802xx000001neB9AAI",
105              "billingAddressId": "@{refBillingAddress.id}",
106              "shippingAddressId": "@{refShippingAddress.id}",
107              "shipFromAddressId": "@{refShipFromAddress.id}",
108              "taxTreatmentId": "1ttxx0000000BOTAA2",
109              "legalEntityId": "0fwxx0000000001AAA",
110              "legalEntityAccountingPeriodId": "1HLxx0000004C92GAE"
111            }
112          },
113          {
114            "referenceId": "refInvoiceLine2",
115            "record": {
116              "attributes": {
117                "type": "InvoiceLine",
118                "method": "POST"
119              },
120              "name": "productName2",
121              "product2Id": "01txx0000006ic4AAA",
122              "invoiceLineStartDate": "2024-11-10",
123              "invoiceLineEndDate": "2024-11-15",
124              "quantity": "10",
125              "unitPrice": "10",
126              "chargeAmount": "100",
127              "invoiceId": "@{refInvoice.id}",
128              "referenceEntityItemId": "802xx000001neB9AAI",
129              "billingAddressId": "@{refBillingAddress.id}",
130              "shippingAddressId": "@{refShippingAddress.id}",
131              "shipFromAddressId": "@{refShipFromAddress.id}",
132              "taxTreatmentId": "1ttxx00000001DpAAI",
133              "legalEntityId": "0fwxx0000000001AAA",
134              "legalEntityAccountingPeriodId": "1HLxx0000004C92GAE"
135            }
136          },
137          {
138            "referenceId": "refInvoiceLineTax",
139            "record": {
140              "attributes": {
141                "type": "InvoiceLineTax",
142                "method": "POST"
143              },
144              "taxAmount": 7.25,
145              "taxCode": "CA-94121",
146              "taxName": "CALIFORNIA",
147              "taxRate": 0.25,
148              "taxEffectiveDate": "2024-11-10",
149              "taxDocumentNumber": "123",
150              "taxExemptAmount": 0,
151              "taxTransactionNumber": "kl",
152              "description": "description for tax Line",
153              "invoiceLineId": "@{refInvoiceLine1.id}"
154            }
155          },
156          {
157            "referenceId": "refInvoiceLineTax1",
158            "record": {
159              "attributes": {
160                "type": "InvoiceLineTax",
161                "method": "POST"
162              },
163              "taxAmount": "10",
164              "taxCode": "CA-94121",
165              "taxName": "CALIFORNIA",
166              "taxRate": 0.25,
167              "taxEffectiveDate": "2024-11-10",
168              "taxDocumentNumber": "123",
169              "taxExemptAmount": 0,
170              "taxTransactionNumber": "125",
171              "invoiceLineId": "@{refInvoiceLine2.id}",
172              "description": "description for tax Line"
173            }
174          }
175        ]
176      }
177    }
178  ]
179}

JSON Example to Ingest Posted Invoices

1{
2  "invoices": [
3    {
4      "taxCalculationStatus": "Posted",
5      "graph": {
6        "graphId": "123",
7        "records": [
8          {
9            "referenceId": "refAccount",
10            "record": {
11              "attributes": {
12                "type": "Account",
13                "method": "GET",
14                "id": "ExternalId__c/123"
15              }
16            }
17          },
18          {
19            "referenceId": "refInvoice",
20            "record": {
21              "attributes": {
22                "type": "Invoice",
23                "method": "POST"
24              },
25              "billingAccountId": "001SG00000njpF3YAI",
26              "billToContactId": "003xx000004Wk8qAAC",
27              "paymentTermId": "2OXxx0000004CFUGA2",
28              "referenceEntityId": "801xx000003GeQQAA0",
29              "status": "Posted",
30              "invoiceDate": "2024-12-19",
31              "currencyIsoCode": "USD",
32              "dueDate": "2024-12-19",
33              "invoiceNumber": "DOC-10",
34              "description": "Sample Invoice",
35              "uniqueIdentifier": "9994b2c4-c0c3-47c3-806f-ae6e1f16bac3"
36            }
37          },
38          {
39            "referenceId": "refBillingAddress",
40            "record": {
41              "attributes": {
42                "type": "InvoiceAddressGroup",
43                "method": "POST"
44              },
45              "street": "123 Main St",
46              "city": "NewYork",
47              "postalCode": "10001",
48              "state": "New York",
49              "country": "US",
50              "longitude": "123.456",
51              "latitude": "78.910",
52              "invoiceId": "@{refInvoice.id}"
53            }
54          },
55          {
56            "referenceId": "refShippingAddress",
57            "record": {
58              "attributes": {
59                "type": "InvoiceAddressGroup",
60                "method": "POST"
61              },
62              "street": "123 Main St",
63              "city": "NewYork",
64              "postalCode": "10001",
65              "state": "New York",
66              "country": "US",
67              "longitude": "123.456",
68              "latitude": "78.910",
69              "invoiceId": "@{refInvoice.id}"
70            }
71          },
72          {
73            "referenceId": "refShipFromAddress",
74            "record": {
75              "attributes": {
76                "type": "InvoiceAddressGroup",
77                "method": "POST"
78              },
79              "street": "1 Market Street",
80              "city": "San Francisco",
81              "postalCode": "94105",
82              "state": "CA",
83              "country": "US",
84              "longitude": "123.456",
85              "latitude": "78.910",
86              "invoiceId": "@{refInvoice.id}"
87            }
88          },
89          {
90            "referenceId": "refInvoiceLine1",
91            "record": {
92              "attributes": {
93                "type": "InvoiceLine",
94                "method": "POST"
95              },
96              "name": "productName1",
97              "product2Id": "01txx0000006ic4AAA",
98              "invoiceLineStartDate": "2024-11-10",
99              "invoiceLineEndDate": "2024-11-13",
100              "quantity": "10",
101              "unitPrice": "10",
102              "chargeAmount": "100",
103              "invoiceId": "@{refInvoice.id}",
104              "referenceEntityItemId": "802xx000001neB9AAI",
105              "billingAddressId": "@{refBillingAddress.id}",
106              "shippingAddressId": "@{refShippingAddress.id}",
107              "shipFromAddressId": "@{refShipFromAddress.id}",
108              "taxTreatmentId": "1ttxx0000000BOTAA2",
109              "legalEntityId": "0fwxx0000000001AAA",
110              "legalEntityAccountingPeriodId": "1HLxx0000004C92GAE"
111            }
112          },
113          {
114            "referenceId": "refInvoiceLine2",
115            "record": {
116              "attributes": {
117                "type": "InvoiceLine",
118                "method": "POST"
119              },
120              "name": "productName2",
121              "product2Id": "01txx0000006ic4AAA",
122              "invoiceLineStartDate": "2024-11-10",
123              "invoiceLineEndDate": "2024-11-15",
124              "quantity": "10",
125              "unitPrice": "10",
126              "chargeAmount": "100",
127              "invoiceId": "@{refInvoice.id}",
128              "referenceEntityItemId": "802xx000001neB9AAI",
129              "billingAddressId": "@{refBillingAddress.id}",
130              "shippingAddressId": "@{refShippingAddress.id}",
131              "shipFromAddressId": "@{refShipFromAddress.id}",
132              "taxTreatmentId": "1ttxx00000001DpAAI",
133              "legalEntityId": "0fwxx0000000001AAA",
134              "legalEntityAccountingPeriodId": "1HLxx0000004C92GAE"
135            }
136          },
137          {
138            "referenceId": "refInvoiceLineTax1",
139            "record": {
140              "attributes": {
141                "type": "InvoiceLineTax",
142                "method": "POST"
143              },
144              "taxAmount": "10",
145              "taxCode": "CA-94121",
146              "taxName": "CALIFORNIA",
147              "taxRate": 0.25,
148              "taxEffectiveDate": "2024-11-10",
149              "taxDocumentNumber": "123",
150              "taxExemptAmount": 0,
151              "taxTransactionNumber": "125",
152              "invoiceLineId": "@{refInvoiceLine1.id}",
153              "description": "Associated tax line."
154            }
155          }
156        ]
157      }
158    }
159  ]
160}

JSON Example to Generate Invoices From Debit Memos

1{
2  "invoices": [
3    {
4      "shouldCalculateTax": true,
5      "taxCalculationStatus": "Estimated",
6      "graph": {
7        "graphId": "CreateInvoice",
8        "records": [
9          {
10            "referenceId": "refInvoice",
11            "record": {
12              "attributes": {
13                "type": "Invoice",
14                "method": "POST"
15              },
16              "accountId": "001SB00001V3RxNYAV",
17              "billToContactId": "003xx000004WhUQAA0",
18              "referenceEntityId": "4DmAAC000008UP70BM",
19              "status": "Draft",
20              "invoiceDate": "2024-12-19",
21              "dueDate": "2024-12-19",
22              "description": "Sample Invoice"
23            }
24          }
25        ]
26      }
27    }
28  ]
29}

Properties

Name	Type	Description	Required or Optional	Available Version
`invoices`	Invoice Ingestion Input[]	List of invoices to be generated or ingested, enabling the submission and processing of multiple invoices in a single request. This API supports one invoice per request. To send 25 requests at a time, see the Composite Batch request.	Required	63.0

Response Body for POST

Invoice Ingestion