--- title: "Order invoice notification" method: POST path: "/api/oms/pvt/orders/{orderId}/invoice" tags: ["Invoice"] --- # Order invoice notification `POST /api/oms/pvt/orders/{orderId}/invoice` This request is used for [invoicing an order](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/2WgQrlHTyVo4hLjhUs1LMT). Entering the order's invoice means it was successfully completed, and the order status can be changed to `invoiced` in the [order flow](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196). 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](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe) scenarios. >❗ To avoid rounding errors, we recommend always sending the object of items being invoiced. ## Partial invoices After adding a [partial invoice](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/q9GPspTb9cHlMeAZfdEUe), 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](https://developers.vtex.com/docs/guides/change-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](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy): | **Role** | **Resource** | | --------------- | ----------------- | | OMS - Full access | Cancel order | | IntegrationProfile - Fulfillment Oms | Cancel order | >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). 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](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). ## Path parameters - `orderId` string, required ## Headers - `Accept` string, required - `Content-Type` string, required ## Request body - object - `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. - `issuanceDate` string, required — The invoice date is when the order was [invoiced](https://help.vtex.com/en/tracks/orders--2xkTisx4SXOWXQel8Jg8sa/2WgQrlHTyVo4hLjhUs1LMT) 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. - `invoiceNumber` string, nullable, required — Unique code that identifies the invoice. When you call this endpoint using the same invoice number, you generate a new `receipt` code. - `invoiceValue` string, 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`. - `invoiceKey` string, nullable — Information about invoice key. - `invoiceUrl` string, nullable — URL of the invoice. Can be used to send the URL of an XML file, for example, which is useful for some integrations. - `embeddedInvoice` string, nullable — XML text of the invoice, not the URL. This field is very important for external marketplace integrations such as Mercado Libre. - `courier` string — The name of the carrier responsible for delivering the order. - `trackingNumber` string, 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 (`""`)*. - `trackingUrl` string, 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 (`""`)*. - `dispatchedDate` string, nullable — Order dispatch date. May be `null`. - `items` object[], required — Array containing the SKUs that are being invoiced. - `id` string, required — ID of the SKU being invoiced. - `price` integer, required — Price in cents of the SKU being invoiced. Do not use a decimal separator, for example, the price $24.99 corresponds to `2499`. You must insert the SKU unitary price because the VTEX system will multiply the price over the quantity. - `description` string — You can use this field for additional information about the SKU being invoiced. - `quantity` integer, required — Quantity currently in inventory of the SKU being invoiced. ## Response `200` OK - object - `date` string — Date and time when the notification was received. - `orderId` string — Identification of the order in the seller. - `receipt` string — 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. ## Changes - **2026-02-04** `47ae096fa36b` — 1 breaking, 2 info - request property `type` was restricted to a list of enum values - added the new `Input` enum value to the request property `type` - added the new `Output` enum value to the request property `type` [Change history](https://skmtc.dev/vtex/apis/orders-api/changes/api/oms/pvt/orders/:orderId/invoice/post.md) --- [API](https://skmtc.dev/vtex/apis/orders-api.md) · [All operations](https://skmtc.dev/vtex/apis/orders-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vtex/orders-api/revisions/cb5fa08e400c/schema)