Graph Record for Invoice Ingestion

A Graph record is an object that’s a part of the graph structure, representing both the fields and relationships among different objects. Each record in the graph can contain attributes, which are fields of the object, and references to other related records.

Invoice ingestion supports a Graph record count of 500. The supported Graph attribute types for invoice ingestion are Account, Contact, Invoice, InvoiceLine, InvoiceLineTax, and InvoiceAddressGroup.

A Graph record has these properties and associated fields.

Field	Description
`referenceId`	Unique identifier of the record that’s used to reference the record in the graph.
`record`	Object containing the actual data for the record.
`record.attributes.type`	Standard object of the referenced record. In this scenario, this field indicates an `InvoiceAddressGroup` attribute type.
`record.attributes.method`	Method that defines the operation on the record. For example, POST to create a record, PUT to update a record, or GET to get record data.

JSON Example

1{
2  "referenceId": "refBillingAddress",
3  "record": {
4    "attributes": {
5      "type": "InvoiceAddressGroup",
6      "method": "POST"
7    },
8    //Contains the actual data
9  }
10}

Account Record

Keep these considerations in mind when you specify an Account record as the Graph attribute type.

The supported Graph attribute method is GET only.
The supported record count that you can specify for each account is one only.
The id field on attributes is the value of the externalId field API Name in Account. Use this field to resolve the Salesforce Account ID from the custom external ID field. See Use an ‘External ID’ to set the values for audit fields.

JSON Example

1{
2  "referenceId": "refAccount", 
3  "record": {
4    "attributes": {
5      "type": "Account",
6      "method": "GET",
7      "id": "AccountId__c/7661eaaf-f527-4dcf-beb3-301f3eddcd9e"
8    }
9  }
10}

Contact Record

Keep these considerations in mind when you specify a Contact record as the Graph attribute type.

The supported Graph attribute method is GET only.
The supported record count that you can specify for Contact is one only.
The id field on attributes is the value of the externalId field API Name in Contact. Use this field to resolve the Salesforce Contact ID from the custom external ID field. See Use an ‘External ID’ to set the values for audit fields.

JSON Example

1{
2  "referenceId": "refContact", 
3  "record": {
4    "attributes": {
5      "type": "Contact",
6      "method": "GET",
7      "id": "ContactId__c/7661eaaf-f527-4dcf-beb3-301f3eddcd9e"
8    }
9  }
10}

Invoice Record

Keep these considerations in mind when you specify an Invoice record as the Graph attribute type.

The supported Graph attribute method is POST only.
The supported record count that you can specify for Invoice is one only.
An invoice with Draft status can’t have a posted date.
You can’t use an invoice with Draft status when the taxCalculationStatus property value is Posted. The taxCalculationStatus property must be Estimated or Pending.
You can’t use an invoice with Posted status when the shouldCalculateTax property is true.
An invoice with Posted status can’t include the Estimated or Pending as the taxCalculationStatus property values. The tax processing status must be Posted.
An invoice with Posted status with an invoice line marked as taxable must include an invoiceLineTax for that invoice line.
An invoice with Posted status with an invoice line marked as nontaxable must not include an invoiceLineTax for that invoice line.
The invoice.CreationMode field value is External. This field differentiates the invoices created from a billing schedule or an invoice ingestion. For invoices created from a billing schedule, the value is Salesforce. For invoices created from an invoice ingestion, the value is External.
The due date of an invoice graph is in the future or with a valid payment term, or your Salesforce org has a default payment term set.

JSON Example

1{
2  "referenceId": "refInvoice",
3  "record": {
4    "attributes": {
5      "type": "Invoice",
6      "method": "POST"
7    },
8    "invoiceDate": "2024-01-01",
9    "billingAccountId": "001xx000003Dzo9AAC",
10    "billToContactId": "003xx000004TzFoAAI",
11    "paymentTermId": "2OXxx0000004CFUGA2",
12    "referenceEntityId": "801xx000003GeQQAA0",
13    "status": "Draft",
14    "currencyIsoCode": "USD",
15    "dueDate": "2024-02-01",
16    "postedDate": "2024-01-02",
17    "invoiceNumber": "INV-12345",
18    "uniqueIdentifier": "1a9380c1-8042-422d-bcc5-70c3f51c2588",
19    "description": "Consulting Services",
20    "shouldExcludePayment": true,
21    "paymentExclusionReason": "Not applicable."
22  }
23}

NAME	Standard Object Field	Description	Required or Optional
`invoiceDate`	Invoice.invoiceDate	Date when the invoice was created or issued.	Required
`billingAccountId`	Invoice.billingAccountId	Billing account associated with this invoice, which you can resolve with the `externalId` field by using the GET method.	Required
`billToContactId`	Invoice.billToContactId	Contact to whom the invoice is billed, which you can resolve with the `externalId` field by using the GET method.	Required
`paymentTermId`	Invoice.paymentTermId	Payment term associated with the invoice. If a value isn’t specified, then the default payment term ID is used.	Optional
`referenceEntityId`	Invoice.referenceEntityId	Reference to a related object, if applicable. To generate invoices from debit memos, specify the debit memo ID as the property value. Make sure that the debit memo is in `Posted` status. Available in API version 66.0 and later. The invoice is generated in `Draft` status.	Optional
`status`	Invoice.status	Status of the invoice. Valid values are `Draft` or `Posted`. The default value is `Draft`.	Optional
`currencyIsoCode`	Invoice.currencyIsoCode	ISO code representing the currency of the invoice. This property must be specified if multi-currency is enabled in the organization.	Optional
`dueDate`	Invoice.dueDate	Due date for the invoice payment. If a value isn’t specified, then this value is set based on the payment term.	Optional
`postedDate`	Invoice.postedDate	Date the invoice was posted to the system. Until API version 64.0, the default value is the current date irrespective of the value that’s specified in the input payload. In API version 65.0 and later, the posted date specified in the input payload is considered.	Required in API version 65.0 and later.
`invoiceNumber`	Invoice.invoiceNumber	Unique identifier for the invoice.	Optional
`uniqueIdentifier`	Invoice.uniqueIdentifier	Unique identifier for the invoice. This property is used as the idempotency key to avoid duplicate invoice generation.	Optional
`description`	Invoice.description	Short description of the invoice or the billed items.	Optional
`shouldExcludePayment`	Invoice.shouldExcludePayment	Indicates whether to exclude the payment during invoice generation and skip creating payment schedules and payment schedule items for the invoice (`true`) or not (`false`). The default value is `false`. Available in API version 68.0 and later.	Optional
`paymentExclusionReason`	Invoice.paymentExclusionReason	Reason for excluding the payment for the invoice. Available in API version 68.0 and later.	Optional

Invoice Line Record

Keep these considerations in mind when you specify an Invoice Line record as the Graph attribute type.

The supported Graph attribute method is POST only.
The Graph must include at least one Graph record with the InvoiceLine attribute type.
The invoice line end date must be greater than or equal to the invoice line start date.

JSON Example

1{
2  "referenceId": "refInvoiceLine",
3  "record": {
4    "attributes": {
5      "type": "InvoiceLine",
6      "method": "POST"
7    },
8    "name": "Parle G",
9    "invoiceLineStartDate": "2024-01-01",
10    "invoiceLineEndDate": "2024-01-31",
11    "quantity": 10,
12    "unitPrice": 25,
13    "chargeAmount": 250,
14    "invoiceId": "@{refInvoice.id}",
15    "shippingAddressId": "@{refShippingAddress.id}",
16    "billingAddressId": "@{refBillingAddress.id}",
17    "referenceEntityItemId": "802xx000001neB9AAI",
18    "taxTreatmentId": "1ttxx0000000BOTAA2",
19    "legalEntityId": "0fwxx0000000001AAA",
20    "legalEntityAccountingPeriodId": "1HLxx0000004C92GAE",
21    "product2Id": "01txx0000006ic4AAA",
22    "usageProductId": "01txx0000006ic5AAA",
23    "isUsageBasedInvoiceLine": false,
24    "usageOverageQuantity": 5,
25    "unitOfMeasureId": "0hExx0000000001EAA",
26    "description": "Sample product description"
27  }
28}

NAME	Standard Object Field	Description	Required or Optional
`name`	InvoiceLine.name	Name or description of the invoice line item.	Required
`invoiceLineStartDate`	InvoiceLine.invoiceLineStartDate	Start date for the invoice line period. For example, the date when the product or service is provided.	Required
`invoiceLineEndDate`	InvoiceLine.invoiceLineEndDate	End date for the invoice line period. For example, the date when the product or service ends.	Required
`quantity`	InvoiceLine.quantity	Quantity of the product or billed service in this invoice line.	Required
`unitPrice`	InvoiceLine.unitPrice	Price per unit of the product or billed service.	Required
`chargeAmount`	InvoiceLine.chargeAmount	Total charge amount for this invoice line, which is calculated as quantity * unit price.	Required
`invoiceId`	InvoiceLine.invoiceId	Reference to the invoice that this invoice line is associated with.	Required
`shippingAddressId`	InvoiceLine.shippingAddressId	Shipping address associated with this invoice line.	Required
`billingAddressId`	InvoiceLine.billingAddressId	Billing address associated with this invoice line.	Required
`referenceEntityItemId`	InvoiceLine.referenceEntityItemId	Reference to a related object record for this invoice line.	Optional
`taxTreatmentId`	InvoiceLine.taxTreatmentId	Tax treatment applied to this invoice line such as taxable or nontaxable. If the `TaxTreatmentId` property isn’t specified in the request, it’s retrieved from the organization’s default values. If the organization’s defaults aren’t set, an error is thrown.	Optional
`legalEntityId`	InvoiceLine.legalEntityId	Legal entity that this invoice line belongs to. If the `LegalEntityId` property isn’t specified in the request, it’s retrieved from the organization’s default values. If the organization’s defaults aren’t set, an error is thrown.	Optional
`legalEntityAccountingPeriodId`	InvoiceLine.legalEntityAccountingPeriodId	Accounting period for the legal entity that this invoice line belongs to.	Optional
`product2Id`	InvoiceLine.product2Id	Identifier for the product that’s billed in this invoice line.	Optional
`usageProductId`	InvoiceLine.usageProductId	Identifier for the usage-based product if this invoice line is for usage-based billing.	Optional
`isUsageBasedInvoiceLine`	InvoiceLine.isUsageBasedInvoiceLine	Boolean value that indicates whether this invoice line is for a usage-based product (`true`) or not (`false`).	Optional
`usageOverageQuantity`	InvoiceLine.usageOverageQuantity	Quantity of usage overage for this invoice line, if applicable.	Optional
`unitOfMeasureId`	InvoiceLine.unitOfMeasureId	Identifier for the unit of measure for the product or service, such as each, kg, or lb.	Optional
`description`	InvoiceLine.description	Description of the invoice line item with additional details.	Optional

Tax Record

Keep these considerations in mind when you specify a Tax record as the Graph attribute type.

The supported Graph attribute method is POST only.
The associated standard object is InvoiceLineTax.
The invoiceLineTax graph record must not include the taxCalculationStatus property value as Pending.

JSON Example

1{
2    "referenceId": "refInvoiceLineTax",
3    "record": {
4        "attributes": {
5            "type": "InvoiceLineTax",
6            "method": "POST"
7        },
8        "taxTransactionNumber": "TX123456789",
9        "taxAmount": 15.00,
10        "taxRate": 0.08,
11        "taxName": "Sales Tax",
12        "taxCode": "TX-SALES",
13        "taxEffectiveDate": "2024-01-01",
14        "invoiceLine": "@{refInvoiceLine.id}",
15        "taxDocumentNumber": "TAXDOC987654",
16        "taxExemptAmount": 0.00,
17        "description": "Exempt from VAT"
18    }
19}

NAME	Standard Object Field	Description	Required or Optional
`taxTransactionNumber`	InvoiceLineTax.taxTransactionNumber	Unique identifier of the tax transaction related to this invoice line tax.	Required
`taxAmount`	InvoiceLineTax.taxAmount	Total tax amount applied to the invoice line.	Required
`taxRate`	InvoiceLineTax.taxRate	Rate at which the tax is applied on the invoice line.	Required
`taxName`	InvoiceLineTax.taxName	Name of the tax applied on the invoice line, such as Sales Tax or Value Added Tax (VAT).	Required
`taxCode`	InvoiceLineTax.taxCode	Tax code that corresponds to the applied tax rate.	Required
`taxEffectiveDate`	InvoiceLineTax.taxEffectiveDate	Effective date from which the tax rate applies.	Required
`invoiceLine`	InvoiceLineTax.invoiceLine	Reference to the invoice line this tax record is associated with.	Required
`taxDocumentNumber`	InvoiceLineTax.taxDocumentNumber	Document number associated with the tax transaction, such as tax return document or government filing number.	Required
`taxExemptAmount`	InvoiceLine.billingAddressId	Billing address associated with this invoice line.	Required
`description`	InvoiceLineTax.description	Additional details about the tax.	Optional

Shipping Address Record

Keep these considerations in mind when you specify a Shipping Address record as the Graph attribute type.

The supported Graph attribute method is POST only.
The associated standard object is InvoiceAddressGroup.

JSON Example

1{
2    "referenceId": "refShippingAddress",
3    "record": {
4        "attributes": {
5            "type": "InvoiceAddressGroup",
6            "method": "POST"
7        },
8        "street": "456 Elm St",
9        "city": "Springfield",
10        "postalCode": "62701",
11        "state": "IL",
12        "country": "USA",
13        "longitude": "-89.6501",
14        "latitude": "39.7817",
15        "invoiceId": "@{refInvoice.id}"
16    }
17}

NAME	Standard Object Field	Description	Required or Optional
`invoiceId`	InvoiceAddressGroup.invoice	Unique identifier of the invoice associated with this shipping address.	Required
`street`	InvoiceAddressGroup.street	Street address where the goods or services are shipped to.	Required
`city`	InvoiceAddressGroup.city	City where the shipment is delivered.	Required
`postalCode`	InvoiceAddressGroup.postalCode	Postal or ZIP code for the shipping address.	Required
`state`	InvoiceAddressGroup.state	State or province of the delivery location.	Required
`country`	InvoiceAddressGroup.country	Country where the shipment is delivered.	Required
`longitude`	InvoiceAddressGroup.longitude	Geographic longitude of the shipping address location for mapping purposes.	Optional
`latitude`	InvoiceAddressGroup.latitude	Geographic latitude of the shipping address location for mapping purposes.	Optional

Billing Address Record

Keep these considerations in mind when you specify a Billing Address record as the Graph attribute type.

The supported Graph attribute method is POST only.
The associated standard object is InvoiceAddressGroup.

JSON Example

1{
2    "referenceId": "refBillingAddress",
3    "record": {
4        "attributes": {
5            "type": "InvoiceAddressGroup",
6            "method": "POST"
7        },
8        "street": "789 Oak St",
9        "city": "Los Angeles",
10        "postalCode": "90001",
11        "state": "CA",
12        "country": "USA",
13        "longitude": "-118.2437",
14        "latitude": "34.0522",
15        "invoiceId": "@{refInvoice.id}"
16    }
17}

NAME	Standard Object Field	Description	Required or Optional
`invoiceId`	InvoiceAddressGroup.invoice	Unique identifier of the invoice associated with this billing address.	Required
`street`	InvoiceAddressGroup.street	Street address for billing purposes.	Required
`city`	InvoiceAddressGroup.city	City for billing address.	Required
`postalCode`	InvoiceAddressGroup.postalCode	Postal or ZIP code for the billing address.	Required
`state`	InvoiceAddressGroup.state	State or province for the billing address.	Required
`country`	InvoiceAddressGroup.country	Country for the billing address.	Required
`longitude`	InvoiceAddressGroup.longitude	Geographic longitude of the billing address location for mapping purposes.	Optional
`latitude`	InvoiceAddressGroup.latitude	Geographic latitude of the billing address location for mapping purposes.	Optional