This page has moved to nuvemshop.dev/en-US/api/resources/unstable/external-invoice.

External Invoice

An External Invoice (also known as a third-party invoice / nota fiscal terceira) represents a fiscal invoice (e.g. an NF-e in Brazil) that was issued by an external system — such as an ERP or a third-party invoicing provider — and is associated with an Order and one of its Fulfillment Orders.

Use this resource to register, update, list, read and remove invoices that were not generated by Nuvemshop but need to be linked to an order.

Unstable version only

This resource is available only in the unstable API version.

Each External Invoice is identified by its key — the NF-e access key, a 44-character string.

Scopes

Property	Explanation
read_orders	Allows you to read one or more external invoices of an order for a merchant.
write_orders	Allows you to create, update and delete external invoices of an order for a merchant. Imported orders are rejected.

Properties

ExternalInvoice

Fields with a null value are omitted from the response.

Field Name	Field Type	Description
key	String	The NF-e access key (44 characters). Uniquely identifies the invoice.
series	String	The invoice series.
number	String	The invoice number.
status	String	The invoice status. One of Authorized, AuthorizedInContingency, Cancelled, Denied.
subtype	String	The invoice subtype. One of sale, return.
store_id	String	The store identifier.
order_id	String	The order identifier.
fulfillment_order_id	String	The fulfillment order identifier the invoice is associated with.
pdf_url	String	URL to the invoice PDF (DANFE). Optional. Omitted when unavailable.
xml_url	String	URL to the invoice XML (NF-e). Optional. Omitted when unavailable.
emission_date	DateTime	Date when the invoice was emitted, in ISO 8601 format. Optional. Omitted when unavailable.
total_value	Decimal	The total value of the invoice. Optional. Omitted when unavailable.
referenced_key	String	The access key (44 characters) of the original invoice a return refers to. Present for returns; otherwise omitted.
cancellation_date	DateTime	Date when the invoice was cancelled, in ISO 8601 format. Optional. Omitted when unavailable.
created_at	DateTime	Date when the invoice was created, in ISO 8601 format.
updated_at	DateTime	Date when the invoice was last updated, in ISO 8601 format.

Allowed values

Field	Allowed values
subtype	sale, return
status	Authorized, AuthorizedInContingency, Cancelled, Denied

Input Request Properties

ExternalInvoiceCreateInput

Used by POST /orders/\{order_id\}/invoices/external.

Field Name	Field Type	Mandatory	Description
fulfillment_order_id	String	✅	The fulfillment order the invoice is associated with.
subtype	String	✅	The invoice subtype. One of sale, return.
status	String	✅	The invoice status. On create, only Authorized or Denied are accepted.
key	String	✅	The NF-e access key. Must be exactly 44 characters.
series	String	✅	The invoice series.
number	String	✅	The invoice number.
pdf_url	String	✅*	URL to the invoice PDF (DANFE). Required unless status is Denied.
xml_url	String		URL to the invoice XML (NF-e).
emission_date	DateTime		Date when the invoice was emitted, in ISO 8601 format. Eg.: 2026-04-04T14:30:00.
total_value	Decimal		The total value of the invoice.
referenced_key	String	✅*	The access key (44 characters) of the original invoice. Required when subtype is return.

* Conditionally required — see the description column.

ExternalInvoiceUpdateInput

Used by PUT /orders/\{order_id\}/invoices/external/\{key\}. All fields are optional; only the fields present in the request are applied.

Field Name	Field Type	Mandatory	Description
status	String		The invoice status. One of Authorized, AuthorizedInContingency, Cancelled, Denied.
pdf_url	String		URL to the invoice PDF (DANFE).
xml_url	String		URL to the invoice XML (NF-e).
cancellation_date	DateTime		Date when the invoice was cancelled, in ISO 8601 format. Eg.: 2026-04-22T10:00:00.

Error

When a request fails, the API returns an error payload with the following shape:

Field Name	Field Type	Description
timestamp	String	When the error occurred. Eg.: 2026-04-04 14:30:00.
status	Integer	The HTTP status code.
message	String[]	A list of human-readable error messages.
path	String	The request URI that produced the error.
error_code	String	A machine-readable error code. Present only when applicable.

{
   "timestamp": "2026-04-04 14:30:00",
   "status": 400,
   "message": [
      "key: size must be between 44 and 44"
   ],
   "path": "/orders/123456/invoices/external"
}

The error_code field is included only for specific errors; validation errors like the example above do not set it.

Endpoints

POST /orders/{order_id}/invoices/external

Create an external invoice for an order.

URL values

Field name	Field Type	Mandatory	Description
store_id	String	✅	Store identifier
order_id	String	✅	Order identifier

Headers

Header	Field Type	Mandatory	Description
Authorization	String	✅	Bearer App token. Eg.: Bearer {app_token}
Content-type	String	✅	The request content-type "application/json"

Notes

• Parameters are sent in body, JSON format.
• Payload type: ExternalInvoiceCreateInput.
• The invoice is processed asynchronously, so a successful request returns 202 Accepted with no body. Because of this, the invoice may take a short moment to become available on the GET endpoints.
• On create, status accepts only Authorized or Denied.
• pdf_url is required unless status is Denied.
• When subtype is return, referenced_key is required and must reference the original invoice access key.
• If an invoice with the same key already exists for the store, the request is accepted and the duplicate is ignored.

Request Payload

Type	Description
ExternalInvoiceCreateInput	The external invoice to be created.

{
   "fulfillment_order_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
   "subtype": "sale",
   "status": "Authorized",
   "key": "35240412345678000190550010000000011000000017",
   "series": "1",
   "number": "1",
   "pdf_url": "https://example.com/invoices/danfe.pdf",
   "xml_url": "https://example.com/invoices/nfe.xml",
   "emission_date": "2026-04-04T14:30:00",
   "total_value": 149.90
}

Responses

HTTP 202 - Accepted

The invoice was accepted for processing. The response has no body.

HTTP 400 - Bad Request

Type	Description
Error	The request payload is invalid.

HTTP 401 - Unauthorized

Type	Description
Error	The Unauthorized Response

PUT /orders/{order_id}/invoices/external/{key}

Update an existing external invoice. Only the fields present in the request are applied.

URL values

Field name	Field Type	Mandatory	Description
store_id	String	✅	Store identifier
order_id	String	✅	Order identifier
key	String	✅	The NF-e access key (44 characters)

Headers

Header	Field Type	Mandatory	Description
Authorization	String	✅	Bearer App token. Eg.: Bearer {app_token}
Content-type	String	✅	The request content-type "application/json"

Notes

• Parameters are sent in body, JSON format.
• Payload type: ExternalInvoiceUpdateInput.
• Only the fields provided in the request are updated.

Request Payload

Type	Description
ExternalInvoiceUpdateInput	The external invoice fields to update.

{
   "status": "Cancelled",
   "cancellation_date": "2026-04-22T10:00:00"
}

Responses

HTTP 200 - Ok

Type	Description
ExternalInvoice	The updated external invoice.

PUT /orders/123456/invoices/external/35240412345678000190550010000000011000000017

{
   "key": "35240412345678000190550010000000011000000017",
   "series": "1",
   "number": "1",
   "status": "Cancelled",
   "subtype": "sale",
   "store_id": "123456",
   "order_id": "123456",
   "fulfillment_order_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
   "pdf_url": "https://example.com/invoices/danfe.pdf",
   "xml_url": "https://example.com/invoices/nfe.xml",
   "emission_date": "2026-04-04T14:30:00",
   "total_value": 149.90,
   "cancellation_date": "2026-04-22T10:00:00",
   "created_at": "2026-04-04T14:31:00",
   "updated_at": "2026-04-22T10:00:05"
}

HTTP 400 - Bad Request

Type	Description
Error	The request payload is invalid.

HTTP 401 - Unauthorized

Type	Description
Error	The Unauthorized Response

HTTP 404 - Not Found

The external invoice was not found for the given order and key. The response has no body.

GET /orders/{order_id}/invoices/external

Retrieve all external invoices from a specific order. Results are sorted by created_at in descending order.

URL values

Field name	Field Type	Mandatory	Description
store_id	String	✅	Store identifier
order_id	String	✅	Order identifier

Headers

Header	Field Type	Mandatory	Description
Authorization	String	✅	Bearer App token. Eg.: Bearer {app_token}
Content-type	String	✅	The request content-type "application/json"

Parameters

Parameter	Explanation
page	Page number to retrieve. Default: 1.
per_page	Number of results per page. Default: 20. Allowed range: 1–50.
fulfillment_order_id	Optional. Filters invoices by the given fulfillment order identifier.

Notes

• The X-Total-Count response header contains the total number of external invoices for the order.

Responses

HTTP 200 - Ok

Type	Description
ExternalInvoice[]	The list of external invoices.

GET /orders/123456/invoices/external

[
   {
      "key": "35240412345678000190550010000000011000000017",
      "series": "1",
      "number": "1",
      "status": "Authorized",
      "subtype": "sale",
      "store_id": "123456",
      "order_id": "123456",
      "fulfillment_order_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "pdf_url": "https://example.com/invoices/danfe.pdf",
      "xml_url": "https://example.com/invoices/nfe.xml",
      "emission_date": "2026-04-04T14:30:00",
      "total_value": 149.90,
      "created_at": "2026-04-04T14:31:00",
      "updated_at": "2026-04-04T14:31:00"
   }
]

HTTP 401 - Unauthorized

Type	Description
Error	The Unauthorized Response

GET /orders/{order_id}/invoices/external/{key}

Retrieve a single external invoice by its access key.

URL values

Field name	Field Type	Mandatory	Description
store_id	String	✅	Store identifier
order_id	String	✅	Order identifier
key	String	✅	The NF-e access key (44 characters)

Headers

Header	Field Type	Mandatory	Description
Authorization	String	✅	Bearer App token. Eg.: Bearer {app_token}
Content-type	String	✅	The request content-type "application/json"

Responses

HTTP 200 - Ok

Type	Description
ExternalInvoice	The external invoice.

GET /orders/123456/invoices/external/35240412345678000190550010000000011000000017

{
   "key": "35240412345678000190550010000000011000000017",
   "series": "1",
   "number": "1",
   "status": "Authorized",
   "subtype": "sale",
   "store_id": "123456",
   "order_id": "123456",
   "fulfillment_order_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
   "pdf_url": "https://example.com/invoices/danfe.pdf",
   "xml_url": "https://example.com/invoices/nfe.xml",
   "emission_date": "2026-04-04T14:30:00",
   "total_value": 149.90,
   "created_at": "2026-04-04T14:31:00",
   "updated_at": "2026-04-04T14:31:00"
}

HTTP 401 - Unauthorized

Type	Description
Error	The Unauthorized Response

HTTP 404 - Not Found

The external invoice was not found for the given order and key. The response has no body.

DELETE /orders/{order_id}/invoices/external/{key}

Remove an external invoice by its access key.

URL values

Field name	Field Type	Mandatory	Description
store_id	String	✅	Store identifier
order_id	String	✅	Order identifier
key	String	✅	The NF-e access key (44 characters)

Headers

Header	Field Type	Mandatory	Description
Authorization	String	✅	Bearer App token. Eg.: Bearer {app_token}
Content-type	String	✅	The request content-type "application/json"

Responses

HTTP 200 - Ok

The external invoice was removed. The response has no body.

HTTP 401 - Unauthorized

Type	Description
Error	The Unauthorized Response

HTTP 404 - Not Found

The external invoice was not found for the given order and key. The response has no body.