Invoice webhook payload

The resource:url for an Invoice webhook payload uses this basic format:

https://marketplace_url/api/appmarket/v1/invoices/invoice_uuid

Here marketplace_url is the main URL for the marketplace (for example, mycompany.byappdirect.com ), and invoice_uuid is a universally unique identifier that the marketplace has generated for this invoice (for example, 69baef3c-57de-4846-becf-5d74489d68e7).

When an Invoice:Added or Invoice:Changed webhook is triggered, the content payload includes the following attributes:

Attribute	Type	Description
id	String	An ID number assigned to the invoice.
uuid	String	The universally unique identifier (uuid) that identifies the invoice.
locale	String	The invoice locale in the standard ISO 639-1 language code + ISO 3166-1 country code format. For example: 'en_US' or 'fr_CA'.
localized	String	Whether the invoice is localized (true), or uses the default marketplace language (false). In some cases, the default language may depend on the individual product.
invoiceNumber	String	The invoice display ID. By default, this matches the billingRelationshipOwnerInvoiceNumber. Deprecated.
billingRelationship OwnerInvoice Number	String	A customizable sequenced ID number which is displayed on the invoice.
partner	String	A code that identifies the marketplace owner.
status	Enum	The status assigned to the invoice. Must be one of PAID, UNPAID, CARRIED, or VOIDED.
currency	Enum	The currency used for amounts on the invoice. See the Currency definition for a list of possible values.
invoiceDate	Date	The date on which the invoice was issued.
paymentTerms: dueDate	Date	The date by which the customer must pay the invoice. Failure to pay by this date may result in penalties such as interest charges, or even subscription suspension or cancellation.
seller	Object	If the original order was placed on behalf of the customer by a reseller or sales agent, information about the user who made the original purchase (the uuid of the user and company).
customer	Object	Information about the user who receives the products or services in the invoices (the uuid of the user and company).
lines	Object	A collection of the individual items in the invoice. Each item in the invoice is represented with a separate InvoiceLine. See Invoice lines below.
amountDue	Number	The amount of money that the customer currently owes for this invoice.
amountPaid	Number	The amount of money that the customer has already paid on this invoice.
subtotal	Number	The sum of the "total" values for all invoice lines in the invoice. See Invoice lines below.
totalTax	Number	The amount of tax added to the invoice.
carriedBalance	Number	If applicable, the credit balance for this customer at the time of the invoice.
creditNote	Boolean	Whether the invoice results in a credit to the customer.
total	Number	The total amount to be paid by the customer on this invoice.
taxReport	Object	A report that details the taxes that were calculated on each line in the invoice. See the Tax report section below.
taxSummary	Object	A list of TaxDetail objects that summarize the taxes on the invoice. Deprecated.
refundInvoice	Boolean	Whether the invoice represents a refund to the customer.
refundedInvoice	String	If refundInvoice is true, the ID for the invoice with the charges that are being refunded.
delegatedToInvoice	String	If applicable, the ID of an invoice to which balances from this invoice have been carried.
carriedInvoices	Object	A list of IDs for the invoices with balances that have been carried forward to this invoice.
users	Object	A list of IDs and other information for all users represented in the invoice lines.
companies	Object	A list of IDs and other information for all companies represented in the invoice lines.
marketplaces	Object	A list of IDs and other information for all marketplaces represented in the invoice lines.
subscriptions	Object	A list of IDs and other information for all subscriptions represented in the invoice lines.
orders	Object	A list of IDs and other information for all orders represented in the invoice lines.
products	Object	A list of IDs and other information for all products represented in the invoice lines.
editions	Object	A list of IDs and other information for all editions represented in the invoice lines.
pricingPlans	Object	A list of IDs and other information for all pricing plans represented in the invoice lines.
discounts	Object	A list of IDs and other information for all discounts represented in the invoice lines.
costTypes	Object	A list of all cost types represented in the invoice lines. For a list of possible values, see the CostType definition.
costPeriods	Object	A list of all period types represented in the invoice lines. For a list of possible values, see the PricingPeriod definition.
costUnits	Object	If any items are priced by unit, a list of all cost units represented in the invoice lines.

Invoice lines

The line object section of the payload matches the REST API InvoiceLine definition, and also includes the following attributes:

Attribute	Type	Description
unitPrice	Number	The price per unit for the charge.
buyer	Object	Information about the customer who purchased this product or service (the uuid of the user and associated company).
provider	Object	Information about the vendor who provides this product or service (the uuid of the user and associated company).
period:start	Date	The first (or starting) date for the billing period that this line represents.
period:end	Date	The last (or ending) date for the billing period that this line represents.
cost	Object	Detailed information about the charge. See the Cost section below.
subscriptionRef	String	The identifier (ID number or uuid) for the subscription being invoiced.
orderRef	String	The identifier (ID number or uuid) for the order associated with this invoice line.
productRef	String	The identifier (ID number or uuid) for the product or service represented in this invoice line.
editionRef	String	The identifier (ID number or uuid) for the edition of the product.
pricingPlanRef	String	The identifier (ID number or uuid) for the pricing plan associated with the edition.
discountRef	String	The identifier (ID number or uuid) for a discount that has been applied to this charge.
quantity	Number	The number of units included in the charge.
total	Number	The total amount that the customer owes for this invoice line, not including tax (unitPrice x quantity).

Cost

The Cost object provides detailed information about a charge (or a discount). It includes the following attributes:

Attribute	Type	Description
type	Enum	A brief descriptor for the charge and how it is billed. Must be one of RECURRING_FLAT, ONE_TIME_FLAT, INCLUDED, SETUP_PER_UNIT, RECURRING_PER_UNIT, ONE_TIME_PER_UNIT, SETUP_FEE, CONTRACT_FEE, DISCOUNT_PER_UNIT, DISCOUNT_FLAT, METERED_USAGE, REACTIVATION_FEE, TRANSFER_FEE, DISCOUNT_SETUP_FEE, DISCOUNT_SETUP_PER_UNIT, ADDITIONAL_FEE, TERMINATION_FEE, or CUSTOM_FEE.
typeCategory	Enum	Whether the charge is RECURRING or a ONE_TIME fee.
unit	String	If the strategy uses units, this field represents the unit name. If not, this field is null.
strategy	Enum	A brief descriptor of how the charge is billed. Must be one of UNIT, FREE, TIERED, FLAT, VOLUME, UNLIMITED, CUSTOM, or PERCENTAGE.
credit	Boolean	Whether this charge represents a credit rather than a cost.
percentage	Boolean	Whether this charge represents a percentage discount (as opposed to a flat amount).

Tax report

The TaxReport object provides detailed information about the taxes applied to this invoice. It includes the following attributes:

Attribute	Type	Description
id	String	The universally unique identifier (uuid) that identifies the tax report.
transactionId	String	An identifier for the transaction on which the taxes were applied.
tenant	String	The code for the marketplace owner.
invoiceNumber	String	An identifier for the invoice to which the tax applies. Should match the invoice billingRelationshipOwnerInvoiceNumber.
consumer	Object	The user who received the products or services that were taxed. This marches the customer in the main invoice.
{...}:userRef	String	The universally unique identifier (uuid) of the user account for the consumer.
{...}:companyRef	String	The universally unique identifier (uuid) for the user's company.
{...}:address	Object	The billing address for the company. This object includes a streetLine1 and streetLine2 for the address, the city, a region (state or province), country, and postalCode (postal or ZIP code).
{...}:companyTax Exemption ReasonCode	String	If applicable, this it the code that describes why this company is exempt from paying tax.
strategy	Enum	A code that identifies the means used to determine the tax. Must be one of FLAT, MULTI_FLAT, AVALARA, or CUSTOM.
currency	Enum	The currency in which the tax is charged. Should match the invoice currency. See the Currency definition for a list of possible values.
chargedAmount	Number	The amount of the tax being charged on an item.
totalTaxAmount	Number	The total amount of tax for the invoice.
details	Object	Detailed information about the tax in this line. See Tax report details below.
summary	Object	A brief summary that includes the taxableAmount, tax strategy and total tax amount.
metadata	Object	Additional information about this item.

Tax report details

The payload also includes the following additional attributes that do not appear in the REST API documentation:

Attribute	Type	Description
taxType	Object	Details of the method used to calculate taxes for the invoice line. May include an id, name, rate, and strategy.
taxableAmount	Number	Amount of money that can be taxed for this invoice line. Typically equal to the invoice total.
taxAmount	Number	Amount of tax calculated for this line.
taxCode	String	If applicable, a code that indicates that this invoice line should use a special tax calculation (Reduced tax rate, tax exemption, etc).
metadata	Object	Additional information about this item.