v60

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-01361201.5 MB

Invoice

Order invoice notification

This request is used for invoicing an order. Entering the order's invoice means it was successfully completed, and the order status can be changed to invoiced in the order flow. Once an order is invoiced, its status cannot be changed.

After the insertion of the invoice, the order's total value will be updated, even in partial invoice scenarios.

❗ To avoid rounding errors, we recommend always sending the object of items being invoiced.

Partial invoices

After adding a partial invoice, the order's value will be updated, corresponding to a partial settled value in the VTEX payment gateway.

Partially invoiced orders cannot be canceled, and cancellation attempts will result in a 400 status code error. If the customer wants to replace or remove items, it is possible to change the order.

The partial invoices feature is available for all VTEX stores. The partial settlement in the gateway is in Beta, and requires a connector with the Payment Provider Protocol.

Returning items

Besides using this endpoint for generating invoices for sold items, you can use it for generating invoices for returned items. You determine this in the request body type field by choosing one of the following values:

Output: selling order invoice.
Input: returning items invoice.

Be aware of generating return invoices only after the full order amount was invoiced, otherwise, no refund will occur.

⚠️ Generating a return (type: Input) invoice with this endpoint will automatically create a refund without the need of additional API requests.

Changing the receipt code

Every time this endpoint is called using the same invoiceNumber, a new receipt code is generated, and it overrides the previous one. By doing this, you cannot change other information, only the receipt code.

Integration with marketplaces

The invoice should be pushed to the fulfillment account, not to the marketplace account. Once the order is invoiced, the seller should use this request to send the invoice information to the marketplace.

This endpoint is also used by the seller to send the order tracking information. However, this only should be done after the seller has the tracking information.

Permissions

Any user or API key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code 403 error. These are the applicable resources for this endpoint:

Product	Category	Resource
OMS	OMS access	Notify invoice
OMS	OMS access	Notify refund

You can create a custom role with that resource or use one of the following predefined roles:

Role	Resource
OMS - Full access	Cancel order
IntegrationProfile - Fulfillment Oms	Cancel order

❗ Assigning a predefined role to users or application keys usually grants permission to multiple License Manager resources. If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see Best practices for using application keys.

To learn more about machine authentication at VTEX, see Authentication overview.

post/api/oms/pvt/orders/{orderId}/invoice

Path parameters

orderIdstring required

Example:1172452900788-01

Unique code that identifies the order whose invoice is being sent.

Headers

Acceptstring required

HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.

Content-Typestring required

Describes the type of the content being sent.

Request body

type'Output' | 'Input' required

The type of invoice. There are two possible values: Output and Input. The Output type should be used when the invoice you are sending is a selling invoice. The Input type should be used when you send a return invoice.

issuanceDatestring required

The invoice date is when the order was invoiced in the VTEX platform, and the IssuanceDate is the date when the merchant registers the order's invoice in the store's system. The IssuanceDate can be different from the invoice date, because the merchant can register the invoice days or even months after order invoicing. You must add date and time in this field.

invoiceNumberstring nullable required

Unique code that identifies the invoice. When you call this endpoint using the same invoice number, you generate a new receipt code.

invoiceValuestring required

Total amount being invoiced in cents. Must be greater than 0. Do not use any decimal separator. For instance, $24.99 should be represented as 2499.

invoiceKeystring nullable

Information about invoice key.

invoiceUrlstring nullable

URL of the invoice. Can be used to send the URL of an XML file, for example, which is useful for some integrations.

embeddedInvoicestring nullable

XML text of the invoice, not the URL. This field is very important for external marketplace integrations such as Mercado Libre.

courierstring

The name of the carrier responsible for delivering the order.

trackingNumberstring nullable

The number code that identifies the order tracking. This field should only be used when sending the tracking information. When the request is used for sending the invoice, this field should be left empty ("").

trackingUrlstring nullable

The URL used to track the order. This field should only be used when sending the tracking information. When the request is used for sending the invoice, this field should be left empty ("").

dispatchedDatestring nullable

Order dispatch date. May be null.

Response

datestring

Date and time when the notification was received.

orderIdstring

Identification of the order in the seller.

receiptstring

Protocol code generated by the update that identifies the receipt. Every time this endpoint is called using the same invoiceNumber, a new receipt code is generated, and it overrides the previous one.