Order
An order is created when a customer completes the checkout process. Orders also can be created through the API.
Table of Contents
Properties
| Property | Explanation |
|---|---|
| id | The unique numeric identifier for the Order. It's different from number |
| token | Specifies the location of the Order |
| store_id | ID of the store the order belongs to |
| contact_email | Email of the buyer |
| contact_phone | Phone of the buyer |
| contact_identification | Identification of the buyer (CPF/CNPJ/DNI/CUIT) |
| number | Unique numberc identifier for an Order used by the shop owner and customers. It's sequential and starts at 100 |
| completed_at | Object containing information about the date when the Order was created. It's the same date than the created_at date, but in a different data type. |
| attributes | A list with the custom attributes for this order |
| customer | Customer that purchased this Order. Only given if the 'read_customers' scope is set for the app |
| products | List of the products purchased by the customer. Contents are explained below and values hold are the ones corresponding to the time the products were purchased |
| note | Customer's note about the order |
| owner_note | Store owner's note about the order |
| coupon | List of coupons applied to the order |
| discount | Total value of the discount applied to the price of the order |
| subtotal | Price of the order before shipping |
| total | Total price of the order including shipping and discounts |
| total_usd | Total price of the order in US dollars |
| currency | The total spent's currency in ISO 4217 format |
| language | Order's language used by the customer during the checkout process |
| gateway | ID of the payment provider that processed the order payment transaction. |
| gateway_id | [Read-only] External transaction ID used by the payment provider. |
| gateway_name | [Read-only] Name of the payment provider of the order. |
| gateway_link | URL of the transaction details page (in the payments app's website). Can be null if the payment app didn't set this URL, or if it's a custom payment method. |
| shipping_address | The customer's shipping address where the order will be shipped |
| billing_name | Billing name for the order |
| billing_phone | Billing phone for the order |
| billing_address | Billing address for the order |
| billing_number | Billing number for the order |
| billing_floor | Billing floor for the order |
| billing_locality | Billing locality for the order |
| billing_zipcode | Billing zipcode for the order |
| billing_city | Billing city for the order |
| billing_province | Billing province for the order |
| billing_country | Billing country code for the order |
| billing_customer_type | Billing customer type (person or company) |
| billing_business_name | Billing business name |
| billing_fiscal_regime | The (Billing Fiscal Regime) is only used in es_MX, and the default is 601. For other countries, the default is null |
| billing_invoice_use | The (Billing Invoice Use) is only used in es_MX, and the default is G01. For other countries, the default is null |
| billing_trade_name | Billing trade name |
| billing_state_registration | Billing state registration |
| billing_document_type | Billing document type |
| extra | A JSON object containing custom information. Can be set via the API or through custom form fields of name "extra[key]" on the cart's checkout form in the storefront |
| storefront | Origin of the order. Possible values are "store" (order created in the storefront), "meli" (order imported from Mercado Libre), "api" (order created via API), "form" (order created in the admin panel with the draft orders feature) or "pos" (order created via point of sale app) |
| checkout_enabled | Deprecated |
| weight | Order's total weight, in kilograms |
| cancelled_at | Date when the order was cancelled in ISO 8601 format |
| closed_at | Date when the order was closed (archived) in ISO 8601 format |
| read_at | Date when the order was marked as read in ISO 8601 format |
| status | Order's status. Possible values are "open", "closed" or "cancelled" |
| payment_status | Order's payment status. Possible values are "authorized", "pending", "paid", "partially_paid", "abandoned", "refunded", "partially_refunded" or "voided" |
| shipping_status | Order's shipping status. Possible values are "unpacked", "shipped" (means "fulfilled"), "unshipped" (means "unfulfilled", only possible in Orders with shipments and not in Digital Orders), "delivered", "partially_packed" (means at least 1 Fulfillment Order was packed), "partially_fulfilled" (means at least 1 Fulfillment Order was shipped). |
| payment_details | A JSON object containing payment details. |
| paid_at | Date when the order was paid in ISO 8601 format. |
| cancel_reason | Reason why the store owner cancelled an Order. Possible values are "customer", "fraud", "inventory" or "other" |
| created_at | Date when the Order was created in ISO 8601 format. It's the same date than the completed_at date, but in a different data type. |
| updated_at | Date when the Order was last updated in ISO 8601 format |
| client_details | Customer details for analytics. |
| app_id | If the order was created via API by an app, ID of the app. Otherwise, null. |
| same_billing_and_shipping_address | "true" if billing address and shipping address are the same, "false" otherwise. |
| total_paid_by_customer | The total amount of money that the Customer paid in the Order. Important: this might not be the same as the Order's total (such as in unpaid Orders or partially paid Orders). Also, the Order's transaction might also not match this value, since some Orders (ie. Orders that were created via Draft Orders) don't have transactions associated to them, as well as Edit Orders allowing to modify the Order's price without affecting associated Transaction. Finally, this price can increase or decrease depending on Order editions. See order/edited Webhook if you would like to be notified of these changes. |
| fulfillments | A list of the Fulfillment Orders of the Order. See Fulfillment Order Resource Page for reference of the contents. Refer to the aggregates parameter for more information. |
The products field has the following contents:
| Property | Explanation |
|---|---|
| id | ID of the line item. A value that uniquely identifies this product within the order. |
| product_id | Product purchased |
| variant_id | Product Variant purchased |
| name | Product's name at the time of purchase |
| price | Product's price at the time of purchase |
| quantity | Quantity purchased |
| weight | Product's weight at the time of purchase |
| width | Product's width at the time of purchase |
| height | Product's height at the time of purchase |
| depth | Product's depth at the time of purchase |
| free_shipping | Indicates if the product has free shipping or not. |
| issues | Possibles issues that can happen to an order. Contents are explained below. |
| properties | An array with values of custom fields |
Important: In our API, it's possible to obtain the same
product_idandvariant_idin different line items.
Why can this happen? For example, an order may have two units of the same variant, but each with different custom fields.
That's why 2 units (quantity) are not sent in the same line item but are instead sent as separate units with different values in thepropertiesarray.
The
products.idhas an incremental value, meaning it exceeds the limits of anint32type and can require support for larger data types, such asint64. It's crucial for the backend to accommodate fields with extended ranges to avoid exceptions that could disrupt the correct import of information.
The issues field has the following content:
| Property | Value Explanation | Issue explanation |
|---|---|---|
| unclaimed_stock | Number of items claimed by the user with insufficient stock | Can happens due to a race condition while the user is trying to pay the order and another user buys the same item. |
Fulfillment Orders
The fulfillment_orders field is a list of Fulfillment Orders as defined here.
By default, only the Fulfillment Order IDs are returned. To get the details it's possible to use Fulfillment Order API or add the parameter aggregates=fulfillment_orders to include the full details in the response. See examples below.
Payment Details
The payment_details field has the following contents:
| Property | Type | Explanation |
|---|---|---|
| method | String | Payment method selected. |
| credit_card_company | String | Credit card company. |
| installments | Integer | Quantity of installments. |
Endpoints
GET /orders
Receive a list of all Orders. Make sure to check out our recommendations on best practices for retrieving orders information in our FAQ section below.
| Parameter | Explanation |
|---|---|
| since_id | Restrict results to after the specified ID |
| status | Show Orders with a given state. Possible values are "any" (default), "open", "closed" or "cancelled" |
| channels | Restrict results to the specified sales channel. Possible values are "form" (draft order created via admin or API), "store" (order created in the storefront), "api" (order created via API - doesn't include draft orders), "meli" (order imported from Mercado Libre) or "pos" (order created via point of sale app) |
| payment_status | Show Orders with a given payment state. Possible values are "any" (default), "pending", "authorized", "paid", "abandoned", "refunded" or "voided" |
| shipping_status | Show Orders with a given shipping state. Possible values are "any" (default), "unpacked", "unfulfilled" (means "unshipped") or "fulfilled" (means "shipped") |
| created_at_min | Show Orders created after date (ISO 8601 format) |
| created_at_max | Show Orders created before date (ISO 8601 format) |
| updated_at_min | Show Orders last updated after date (ISO 8601 format) |
| updated_at_max | Show Orders last updated before date (ISO 8601 format) |
| total_min | Show Orders with total value bigger or equals than the specified value |
| total_max | Show Orders with total value lower or equals than the specified value |
| customer_ids | Restrict results to the specified customer IDs (comma-separated) |
| page | Page to show |
| per_page | Amount of results |
| fields | Comma-separated list of fields to include in the response |
| q | Search Orders by the given number; or containing the given text in the customer name or email |
| app_id | Show orders created by a given app |
| payment_methods | Show orders with a given payment method |
| payment_provider | Show orders with a given payment provider |
| aggregates | One possible value: fulfillment_orders. Enables an array called fulfillments that displays partial information of the Fulfillment Order. If wou want to get the complete information of the Fulfillment Order, you can use the Fulfillment Order Resource or fetch the single Order with the corresponding aggregates value. |
GET /orders
HTTP/1.1 200 OK
[
{
"id": 871254203,
"token": "b872a1befbcde5aaf0517ecbcc910f5dc005350e",
"store_id": "817495",
"contact_email": "buyer@tiendanube.com",
"contact_name": "Maria Silva",
"contact_phone": "+551533276436",
"contact_identification": "75839566500",
"billing_name": "Maria",
"billing_phone": "+551533276436",
"billing_address": "Rua Doutor Azevedo Sampaio",
"billing_number": "50",
"billing_floor": "",
"billing_locality": "Centro",
"billing_zipcode": "18010220",
"billing_city": "Sorocaba",
"billing_province": "São Paulo",
"billing_country": "BR",
"coupon": [],
"promotional_discount": {
"id": null,
"store_id": 817495,
"order_id": "871254203",
"created_at": "2022-11-15T19:37:08+0000",
"total_discount_amount": "0.00",
"contents": [],
"promotions_applied": []
},
"subtotal": "6000.00",
"discount": "600.00",
"discount_coupon": "0.00",
"discount_gateway": "600.00",
"total": "5400.00",
"total_usd": "40.79",
"checkout_enabled": true,
"weight": "0.000",
"currency": "ARS",
"language": "es",
"gateway": "offline",
"gateway_id": null,
"gateway_name": "Transferencia Bancaria",
"extra": {},
"storefront": "store",
"note": "",
"created_at": "2022-11-15T19:36:59+0000",
"updated_at": "2022-11-15T19:37:08+0000",
"completed_at": {
"date": "2022-11-15 19:36:59.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"payment_details": {
"method": "custom",
"credit_card_company": null,
"installments": 1
},
"same_billing_and_shipping_address": false,
"attributes": [],
"customer": {
"id": 105799009,
"name": "Maria Silva",
"email": "buyer@tiendanube.com",
"identification": "75839566500",
"phone": "+551533276436",
"note": null,
"default_address": {
"address": "Evergreen Terrace",
"city": "New York",
"country": "US",
"created_at": "2022-11-15T19:36:59+0000",
"default": true,
"floor": "Apartment 8",
"id": 80189931,
"locality": "Bronx",
"name": "John Doe",
"number": "742",
"phone": "john.doe@example.com",
"province": "New York",
"updated_at": "2022-11-15T19:36:59+0000",
"zipcode": "10451"
},
"addresses": [
{
"address": "Evergreen Terrace",
"city": "New York",
"country": "US",
"created_at": "2022-11-15T19:36:59+0000",
"default": true,
"floor": "Apartment 8",
"id": 80189931,
"locality": "Bronx",
"name": "John Doe",
"number": "742",
"phone": "john.doe@example.com",
"province": "New York",
"updated_at": "2022-11-15T19:36:59+0000",
"zipcode": "10451"
}
],
"billing_name": "Maria",
"billing_phone": "+551533276436",
"billing_address": "Rua Doutor Azevedo Sampaio",
"billing_number": "50",
"billing_floor": "",
"billing_locality": "Centro",
"billing_zipcode": "18010220",
"billing_city": "Sorocaba",
"billing_province": "São Paulo",
"billing_country": "BR",
"extra": {},
"total_spent": "27.00",
"total_spent_currency": "USD",
"last_order_id": 871254203,
"active": false,
"first_interaction": "2022-11-15T19:36:59+0000",
"created_at": "2022-11-15T19:36:59+0000",
"updated_at": "2022-11-15T19:36:59+0000"
},
"products": [
{
"id": 1069053829,
"depth": "0.00",
"height": "0.00",
"name": "Mesa de Roble",
"price": "6000.00",
"compare_at_price": "37.77",
"product_id": 111334785,
"image": {
"id": 277896749,
"product_id": 111334785,
"src": "https://d2r9epyceweg5n.cloudfront.net/stores/817/495/products/pexels-olya-prutskova-89764951-74e3f47763f1aec3ec16448436206687-1024-1024.jpg",
"position": 1,
"alt": [],
"created_at": "2022-02-14T13:00:03+0000",
"updated_at": "2022-10-28T21:52:37+0000"
},
"quantity": "1",
"free_shipping": false,
"weight": "0.00",
"width": "0.00",
"variant_id": "426215948",
"variant_values": [],
"properties": [],
"sku": "12389012348124801234890",
"barcode": null
}
],
"number": 306,
"cancel_reason": null,
"owner_note": null,
"cancelled_at": null,
"closed_at": null,
"read_at": null,
"status": "open",
"payment_status": "pending",
"gateway_link": null,
"shipping_address": {
"address": "Evergreen Terrace",
"city": "New York",
"country": "US",
"created_at": "2022-11-15T19:23:59+0000",
"default": false,
"floor": "Apartment 8",
"id": 0,
"locality": "Bronx",
"name": "John Doe",
"number": "742",
"phone": "john.doe@example.com",
"province": "New York",
"updated_at": "2022-11-15T19:37:08+0000",
"zipcode": "10451",
"customs": null
},
"shipping_status": "unpacked",
"paid_at": null,
"client_details": {
"browser_ip": "181.16.41.4",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36"
},
"app_id": null
}
]
GET /orders?aggregates=fulfillment_orders
HTTP/1.1 200 OK
[
{
"id": 871254203,
"token": "b872a1befbcde5aaf0517ecbcc910f5dc005350e",
"store_id": "817495",
... // All fields from GET /orders are included in the response
"fulfillment_orders": [
{
"id": "01BX5ZZKBKACTAV9WEVGEMMVRZ",
"number": "123456",
"total_quantity": 12,
"total_weight": 12.12,
"total_price": {
"value": 123.45,
"currency": "BRL",
},
"assigned_location": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Location name",
"address": {
"zipcode": "12910802",
"street": "Some Street",
"number": "100",
"floor": "Some Floor",
"locality": "Some Locality",
"city": "Some City",
"reference": "Some Reference",
"between_streets": "Some Between Streets",
"province": {
"code": "SP",
"name": "São Paulo"
},
"region": {
"code": "SE",
"name": "Sudeste"
},
"country": {
"code": "BR",
"name": "Brasil"
}
}
},
"line_items": [
{
"id": "12345",
"quantity": 1,
"order_line_item_id": "12345678",
"created_at": "2022-11-24T10:20:19+00:00",
"updated_at": "2022-11-24T10:20:19+00:00"
}
],
"recipient": {
"name": "Recipient name",
"phone": "11988864311",
"identifier": "11223344B",
},
"shipping": {
"type": "pickup|ship",
"carrier": {
"name": "Some Carrier Name",
"id": "12345"
},
"option": {
"name": "Some Option Name",
"code": "some-option-code",
"reference": "some-option-ref"
},
"merchant_cost": {
"value": 123.14,
"currency": "BRL"
},
"consumer_cost": {
"value": 123.14,
"currency": "BRL"
},
"min_delivery_date": "2022-11-24T10:20:19+00:00" || null,
"max_delivery_date": "2022-11-25T10:20:19+00:00" || null,
"pickup_details": {
"id": "pickup-option-id",
"name": "Some option pickup detail name",
"address": {
"zipcode": "12910802",
"street": "Some Street",
"number": "100",
"floor": "Some Floor",
"locality": "Some Locality",
"city": "Some City",
"reference": "Some Reference",
"between_streets": "Some Between Streets",
"province": {
"name": "São Paulo",
"code": "SP"
},
"region": {
"name": "Sudeste",
"code": "SE"
},
"country": {
"name": "Brasil",
"code": "BR"
}
}
}
},
"destination": {
"zipcode": "12910802",
"street": "Some Street",
"number": "100",
"floor": "Some Floor",
"locality": "Some Locality",
"city": "Some City",
"reference": "Some Reference",
"between_streets": "Some Between Streets",
"province": {
"name": "São Paulo",
"code": "SP"
},
"region": {
"name": "Sudeste",
"code": "SE"
},
"country": {
"name": "Brasil",
"code": "BR"
}
},
"status": "PENDING",
"tracking_info": {
"url": null,
"code": null
},
"fulfilled_at": null,
"created_at": "2022-11-24T10:20:19+00:00",
"updated_at": "2022-11-24T10:20:19+00:00"
}]
}
]
GET /orders?fields=id,number,price_usd
HTTP/1.1 200 OK
[
{
"id": 450789469,
"number": "101",
"price_usd": "58.00"
}
]
GET /orders/{id}
Receive a single Order by its id.
If you would like to retrieve a Cart instead, refer to the Cart resource.
| Parameter | Explanation |
|---|---|
| fields | Comma-separated list of fields to include in the response |
| aggregates | One possible value: fulfillment_orders. Enables an array called fulfillments that displays the information of the Fulfillment Order. |
GET /orders/871254203
HTTP/1.1 200 OK
{
"id": 871254203,
"token": "b872a1befbcde5aaf0517ecbcc910f5dc005350e",
"store_id": "817495",
"contact_email": "buyer@tiendanube.com",
"contact_name": "Maria Silva",
"contact_phone": "+551533276436",
"contact_identification": "75839566500",
"billing_name": "Maria",
"billing_phone": "+551533276436",
"billing_address": "Rua Doutor Azevedo Sampaio",
"billing_number": "50",
"billing_floor": "",
"billing_locality": "Centro",
"billing_zipcode": "18010220",
"billing_city": "Sorocaba",
"billing_province": "São Paulo",
"billing_country": "BR",
"billing_customer_type": "company",
"billing_business_name": "Nuvem Shop LTDA",
"billing_trade_name": "Nuvem Shop",
"billing_state_registration": "388108598269",
"billing_fiscal_regime": "601",
"billing_invoice_use": "G01",
"billing_document_type": "cnpj",
"coupon": [],
"promotional_discount": {
"id": null,
"store_id": 817495,
"order_id": "871254203",
"created_at": "2022-11-15T19:37:08+0000",
"total_discount_amount": "0.00",
"contents": [],
"promotions_applied": []
},
"subtotal": "6000.00",
"discount": "600.00",
"discount_coupon": "0.00",
"discount_gateway": "600.00",
"total": "5400.00",
"total_usd": "40.79",
"checkout_enabled": true,
"weight": "0.000",
"currency": "ARS",
"language": "es",
"gateway": "offline",
"gateway_id": null,
"gateway_name": "Transferencia Bancaria",
"extra": {},
"storefront": "store",
"note": "",
"created_at": "2022-11-15T19:36:59+0000",
"updated_at": "2022-11-15T19:37:08+0000",
"completed_at": {
"date": "2022-11-15 19:36:59.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"payment_details": {
"method": "custom",
"credit_card_company": null,
"installments": 1
},
"same_billing_and_shipping_address": false,
"attributes": [],
"customer": {
"id": 105799009,
"name": "Maria Silva",
"email": "buyer@tiendanube.com",
"identification": "75839566500",
"phone": "+551533276436",
"note": null,
"default_address": {
"address": "Evergreen Terrace",
"city": "New York",
"country": "US",
"created_at": "2022-11-15T19:36:59+0000",
"default": true,
"floor": "Apartment 8",
"id": 80189931,
"locality": "Bronx",
"name": "John Doe",
"number": "742",
"phone": "john.doe@example.com",
"province": "New York",
"updated_at": "2022-11-15T19:36:59+0000",
"zipcode": "10451"
},
"addresses": [
{
"address": "Evergreen Terrace",
"city": "New York",
"country": "US",
"created_at": "2022-11-15T19:36:59+0000",
"default": true,
"floor": "Apartment 8",
"id": 80189931,
"locality": "Bronx",
"name": "John Doe",
"number": "742",
"phone": "john.doe@example.com",
"province": "New York",
"updated_at": "2022-11-15T19:36:59+0000",
"zipcode": "10451"
}
],
"billing_name": "Maria",
"billing_phone": "+551533276436",
"billing_address": "Rua Doutor Azevedo Sampaio",
"billing_number": "50",
"billing_floor": "",
"billing_locality": "Centro",
"billing_zipcode": "18010220",
"billing_city": "Sorocaba",
"billing_province": "São Paulo",
"billing_country": "BR",
"extra": {},
"total_spent": "27.00",
"total_spent_currency": "USD",
"last_order_id": 871254203,
"active": false,
"first_interaction": "2022-11-15T19:36:59+0000",
"created_at": "2022-11-15T19:36:59+0000",
"updated_at": "2022-11-15T19:36:59+0000"
},
"products": [
{
"id": 1069053829,
"depth": "0.00",
"height": "0.00",
"name": "Mesa de Roble",
"price": "6000.00",
"compare_at_price": "37.77",
"product_id": 111334785,
"image": {
"id": 277896749,
"product_id": 111334785,
"src": "https://d2r9epyceweg5n.cloudfront.net/stores/817/495/products/pexels-olya-prutskova-89764951-74e3f47763f1aec3ec16448436206687-1024-1024.jpg",
"position": 1,
"alt": [],
"created_at": "2022-02-14T13:00:03+0000",
"updated_at": "2022-10-28T21:52:37+0000"
},
"quantity": "1",
"free_shipping": false,
"weight": "0.00",
"width": "0.00",
"variant_id": "426215948",
"variant_values": [],
"properties": [],
"sku": "12389012348124801234890",
"barcode": null
}
],
"number": 306,
"cancel_reason": null,
"owner_note": null,
"cancelled_at": null,
"closed_at": null,
"read_at": null,
"status": "open",
"payment_status": "pending",
"gateway_link": null,
"shipping_address": {
"address": "Evergreen Terrace",
"city": "New York",
"country": "US",
"created_at": "2022-11-15T19:23:59+0000",
"default": false,
"floor": "Apartment 8",
"id": 0,
"locality": "Bronx",
"name": "John Doe",
"number": "742",
"phone": "john.doe@example.com",
"province": "New York",
"updated_at": "2022-11-15T19:37:08+0000",
"zipcode": "10451",
"customs": null
},
"shipping_status": "unpacked",
"fulfillments": [],
"paid_at": null,
"client_details": {
"browser_ip": "181.16.41.4",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36"
},
"app_id": null
}
GET /orders/{id}/history/values
Receive a list of all Order's total value alterations.
Actions that may alter an Order's total are either editing or refunding an Order. Each modification carries the payment status associated to it, and while it may be related to a Transaction resource it doesn't require one (ie. Draft Orders will also generate this events even though they don't have a Transaction associated to them).
Important: you will see we sometimes refer to these modifications as "transactions". They are not to be confused with the Transaction resource from the Payments Domain, since these rely on a model that is not required for an Order to exist. While these internal transactions might trigger the creation of a new Transaction and therefore have a connection to it, they don't require it. For now, we are not creating Transaction resources beyond the initial one an Order might have when it is created.
| Parameter | Explanation |
|---|---|
| status | The payment status of the Order's value transaction. Possible values are "PENDING", "CANCELLED" or "PAID". Note that if the transaction was not paid and it changes again (ie. an Order with a Pending payment is edited) then the corresponding entry will be marked as "CANCELLED", so "PENDING" is only possible for the most recent value in the history. Also, note that "PAID" in this context might mean that either the Customer or the Merchant paid it, depending of if the total_paid_diff is positive (Customer paid it) or negative (Merchat paid it, it is a partial or full refund). |
| total_delta | The difference between the previous Order value and the new one. |
| total_paid_diff | The amount the Customer / Merchant paid in that Order's transaction state. Note that this value does not have a 1 to 1 correlation to total_delta, it can be higher or lower depending on the aggregate of previous transactions that were never paid. This value is only non-zero if the status is "PAID". |
| gateway_method | The gateway / payment method the Customer / Merchant used to pay or refund the transaction. Possible values are "credit_card", "debit_card", "cash", "wire_transfer", "pix" or "other". |
| gateway_name | When "other" value is given for gateway_method, this field includes a human-readable custom name for the gateway. Otherwise, null is returned. |
| closed_at | Datetime at which the transaciton transitioned to a final state (from "PENDING" to another state). |
| happened_at | Datetime at which the Order's total modification happened. |
HTTP/1.1 200 OK
[
{
"status": "CANCELLED",
"total_delta": 3750,
"total_paid_diff": 0,
"gateway_method": null,
"gateway_name": null,
"closed_at": "2025-04-08T18:19:40+00:00",
"happened_at": "2025-04-08T18:19:15+00:00"
},
{
"status": "PAID",
"total_delta": 3750,
"total_paid_diff": 7500,
"gateway_method": "cash",
"gateway_name": null,
"closed_at": "2025-04-08T18:24:15+0000",
"happened_at": "2025-04-08T18:19:40+00:00"
}
]
GET /orders/{id}/history/editions
Receive a list of all Order's editions.
This is intended as a small change log for the changes that an edition made. Actual changed information will be overwritten in the original Orders' fields.
| Parameter | Explanation |
|---|---|
| product_changes | Contains information about the changes made to the products in the edition. |
| shipping_costs | Contains information about the changes in Shipping costs derived from the products changes. |
| transaction_information | Contains information about the related transaction that the edition generated in the Order. See here for object contents reference. |
| reason | Human-readable text detailing why the edition was made, typically filled out by the Merchant. |
| happened_at | Datetime at which the Order's edition happened. |
Objects
Product Change
| Value | Description |
|---|---|
| type | "ADD" if the product was added, "REMOVED" if it was removed from the Order. This is only the action, for the quantity added or removed see the quantity properties. |
| modified_stock | Indicates if the stock was modified or not. |
| previous_quantity | The line item quantity before the edition. |
| new_quantity | The line item quantity after the edition. |
| product_name | The name of the line item that was modified. |
Shipping Cost
| Value | Description |
|---|---|
| fulfillment_number | The number of the Fulfillment Order related to the shipping cost. |
| previous_merchant_cost | The previous Shipping cost for the Merchant. |
| new_merchant_cost | The new Shipping cost for the Merchant. |
| previous_consumer_cost | The previous Shipping cost for the Customer. |
| new_consumer_cost | The new Shipping cost for the Customer. |
HTTP/1.1 200 OK
[
{
"product_changes": [
{
"type": "ADD",
"modified_stock": true,
"previous_quantity": 0,
"new_quantity": 1,
"product_name": "Pantalon de cuero (Beige)"
}
],
"shipping_costs": [
{
"fulfillment_number": 1,
"previous_merchant_cost": 200,
"new_merchant_cost": 500,
"previous_consumer_cost": 200,
"new_consumer_cost": 500
}
],
"transaction_information": {
"status": "CANCELLED",
"total_delta": 3750,
"total_paid_diff": 0,
"gateway_method": null,
"gateway_name": null,
"closed_at": null,
"happened_at": "2025-04-08T18:19:15+00:00"
},
"reason": null,
"happened_at": "2025-04-08T18:19:15+00:00"
},
{
"product_changes": [
{
"type": "ADD",
"modified_stock": true,
"previous_quantity": 1,
"new_quantity": 2,
"product_name": "Pantalon de cuero (Beige)"
}
],
"shipping_costs": [
{
"fulfillment_number": 1,
"previous_merchant_cost": 500,
"new_merchant_cost": 500,
"previous_consumer_cost": 500,
"new_consumer_cost": 500
}
],
"transaction_information": {
"status": "PAID",
"total_delta": 3750,
"total_paid_diff": 7500,
"gateway_method": "cash",
"gateway_name": null,
"closed_at": "2025-04-08T18:24:15+0000",
"happened_at": "2025-04-08T18:19:40+00:00"
},
"reason": null,
"happened_at": "2025-04-08T18:19:40+00:00"
}
]
POST /orders/
Create an Order.
| Parameter | Description | Required |
|---|---|---|
| currency | The order currency code (ISO 4217 format). The default is the store currency. | No |
| language | The language code (ISO 639-1 format). The default is the store main language. | No |
| gateway | The order's payment gateway (Payment Gateway). The default is not-provided. | Yes |
| payment_status | The order's payment status (Payment Status). The default is pending. | No |
| status | The order's status (Order Status). The default is open. | No |
| fulfillment | The order's status (Order Status). The default is unpacked. | No |
| products | Order's products list (Product). | Yes |
| total | The sum of all products prices, shipping costs and discounts. Must be positive. If not specified, it's calculated considering the provided costs and discounts. | No |
| inventory_behaviour | The inventory behaviour that the order must perform (Inventory Behaviour). | No |
| customer | The customer object (Customer). | Yes |
| note | An additional customer note for the order. | No |
| billing_address | The customer's billing address object (Address). | Yes |
| shipping_address | The customer's shipping address object (Address). | Yes |
| shipping_pickup_type | The shipping pickup type (Shipping Type). The default is pickup. | Yes |
| shipping | The shipping method (Shipping Method). The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | Yes |
| shipping_option | The order's shipping option nice name. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | Yes |
| shipping_tracking_number | The order's shipping tracking number | No |
| shipping_cost_customer | The customer's shipping cost double value. The value 0 means free shipping. The default is 0. | Yes |
| shipping_cost_owner | The owner's shipping cost double value. | No |
| send_confirmation_email | Send the order confirmation email to the customer . The default is false. | No |
| send_fulfillment_email | Send the order fulfillment email to the customer . The default is false. | No |
| location_id | Location id from where the stock will be decreased . Must be string. | No |
Objects
Customer
| Value | Description | Type | Required |
|---|---|---|---|
| name | The customer's name. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
The customer's email address. The defaults are email@naoinformado.com for pt_BR and email@noinformado.com in every other cases (es_AR, es_MX, es_CO). | Yes | ||
| phone | The customer's phone number | String | No |
| document | The customer's document number | String | No |
Address
| Value | Description | Type | Required |
|---|---|---|---|
| first_name | The customer's first name. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| last_name | The customer's last name. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| address | The customer's street. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| number | The address's number. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| floor | The address's complement. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | No |
| locality | The address's locality. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | No |
| city | The address's city. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| province | The address's province. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| zipcode | The address's postal code. The default is 0000. | String | Yes |
| country | The address's country (ISO 3166-1 Format). The default is the store country. | String | Yes |
| phone | The address's phone number. | String | No |
Shipping_Address
| Value | Description | Type | Required |
|---|---|---|---|
| first_name | The customer's first name. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| last_name | The customer's last name. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| address | The customer's street. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| number | The shipping_address number. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| floor | The shipping_address complement. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | No |
| locality | The shipping_address locality. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | No |
| city | The shipping_address city. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| province | The shipping_address province. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | Yes |
| zipcode | The shipping_address postal code. The default is 0000. | String | Yes |
| country | The shipping_address country (ISO 3166-1 Format). The default is the store country. | String | Yes |
| phone | The shipping_address phone number. The defaults are Não informado for pt_BR and No informado in every other cases (es_AR, es_MX, es_CO). | String | No |
| customs | The customs fields of the shipping address. this field can receive any custom value within the object. The default is null | Object | No |
Product
| Value | Description | Type | Required |
|---|---|---|---|
| variant_id | The product variant ID | Integer | Yes |
| quantity | The product quantity | Integer | Yes |
| price | The item price. Defaults to tiendanube's product variant price. | Double | No |
Order Status
| Value | Description |
|---|---|
| open | The order is open |
| closed | The order is closed |
| cancelled | The order is cancelled |
Payment Status
| Value | Description |
|---|---|
| pending | The payment confirmation is pending |
| authorized | The payment was authorized but not captured yet |
| paid | The payment was successfully confirmed and captured |
| voided | The payment confirmation is voided |
| refunded | The payment was refunded to the customer |
| abandoned | The payment confirmation is abandoned |
Payment Gateway
| Value | Description |
|---|---|
| offline | Offline payment gateway |
| mercadopago | Mercado Pago |
| pagseguro | PagSeguro |
| payu | Payu |
| not-provided | The payment gateway is not provided |
Shipping Type
| Value | Description |
|---|---|
| ship | Home delivery |
| pickup | Pickup in a physical location |
Shipping Method
| Value | Description |
|---|---|
| branch | Store branches |
| correios | Brazilian Correios |
| correo-argentino | Correo Argentino |
| oca-partner-ar | OCA |
| table | Custom |
| not-provided | The shipping method was not provided |
Inventory Behaviour
| Value | Description |
|---|---|
| bypass | Do not claim inventory (default) |
| claim | Attempt to claim inventory, it could prevent order creation |
Billing Fiscal Regime
The Billing Fiscal Regime is only used in es_MX (Régimen fiscal).
| Value | Description |
|---|---|
| 601 | General de Ley Personas Morales (default) |
| 603 | Personas Morales con Fines no Lucrativos |
| 610 | Residentes en el Extranjero sin Establecimiento Permanente en México |
| 620 | Sociedades Cooperativas de Producción que optan por diferir sus ingresos |
| 622 | Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras |
| 623 | Opcional para Grupos de Sociedades |
| 624 | Attempt to claim inventory, it could prevent order creation |
| 626 | Régimen Simplificado de Confianza |
Billing Invoice Use
The Billing Invoice Use is only used in es_MX (Uso de factura).
| Value | Description |
|---|---|
| G01 | General de Ley Personas Morales (default) |
| G02 | Devoluciones, descuentos o bonificaciones |
| G03 | Gastos en general |
| I01 | Construcciones |
| I02 | Mobiliario y equipo de oficina por inversiones |
| I03 | Equipo de transporte |
| I04 | Equipo de computo y accesorios |
| I05 | Dados, troqueles, moldes, matrices y herramental |
| I06 | Comunicaciones telefónicas |
| I07 | Comunicaciones satelitales |
| I08 | Otra maquinaria y equipo |
| S01 | Sin efectos fiscales |
| CP01 | Pagos |
POST /orders/
HTTP/1.1 201 Created
{
"id": 871310835,
"token": "d928449fdd060fb7f3854c681923c28cfbccbcc1",
"store_id": 817495,
"contact_email": "john.doe@example.com",
"contact_name": "John Doe",
"contact_phone": "+55 11 99999-9999",
"contact_identification": null,
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"coupon": [],
"promotional_discount": {
"id": null,
"store_id": 817495,
"order_id": 871310835,
"created_at": "2022-11-15T19:47:32+0000",
"total_discount_amount": "0.00",
"contents": [],
"promotions_applied": []
},
"subtotal": "80.00",
"discount": "0.00",
"discount_coupon": "0.00",
"discount_gateway": "0.00",
"total": "80.00",
"total_usd": "80.00",
"checkout_enabled": true,
"weight": "0.000",
"currency": "USD",
"language": "es",
"gateway": "not-provided",
"gateway_id": null,
"gateway_name": "",
"extra": {},
"storefront": "api",
"note": null,
"created_at": "2022-11-15T19:47:32+0000",
"updated_at": "2022-11-15T19:47:32+0000",
"completed_at": {
"date": "2022-11-15 19:47:32.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"payment_details": {
"method": null,
"credit_card_company": null,
"installments": 1
},
"attributes": [],
"customer": {
"id": 44769493,
"name": "John Doe",
"email": "john.doe@example.com",
"identification": null,
"phone": "+55 11 99999-9999",
"note": null,
"default_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
"addresses": [
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": null,
"created_at": "2020-09-11T18:06:09+0000",
"default": false,
"floor": "",
"id": 28900058,
"locality": "",
"name": "John Doe",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2020-09-11T18:06:09+0000",
"zipcode": "97475"
},
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-15T18:55:48+0000",
"default": false,
"floor": null,
"id": 52249003,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-15T18:55:48+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-24T14:01:01+0000",
"default": false,
"floor": null,
"id": 52781492,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-24T14:01:01+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
{
"address": "Fake Street",
"city": "Rosario",
"country": "AR",
"created_at": "2021-09-27T15:39:31+0000",
"default": false,
"floor": "",
"id": 52933588,
"locality": "",
"name": "John Doe",
"number": "123",
"phone": "+55 11 99999-9999",
"province": "Santa Fe",
"updated_at": "2021-09-27T15:39:31+0000",
"zipcode": "2000"
},
{
"address": null,
"city": null,
"country": "AR",
"created_at": "2021-09-27T15:43:15+0000",
"default": false,
"floor": null,
"id": 52933858,
"locality": null,
"name": "John Doe",
"number": null,
"phone": "+55 11 99999-9999",
"province": null,
"updated_at": "2021-09-27T15:43:15+0000",
"zipcode": null
}
],
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"extra": {},
"total_spent": "187.50",
"total_spent_currency": "USD",
"last_order_id": 871310835,
"active": false,
"first_interaction": "2022-11-15T19:47:32+0000",
"created_at": "2020-09-11T18:06:09+0000",
"updated_at": "2022-11-15T19:47:32+0000"
},
"products": [
{
"id": 1069079649,
"depth": "0.00",
"height": "0.00",
"name": "Producto B",
"price": "40.00",
"compare_at_price": "40.00",
"product_id": 63021345,
"image": {
"id": 0,
"product_id": 0,
"src": "https://d2r9epyceweg5n.cloudfront.net/assets/stores/img/no-photo-1024-1024.png",
"position": 0,
"alt": [],
"created_at": "2022-11-15T19:47:33+0000",
"updated_at": "2022-11-15T19:47:33+0000"
},
"quantity": 2,
"free_shipping": false,
"weight": "0.00",
"width": "0.00",
"variant_id": 194113141,
"variant_values": [],
"properties": [],
"sku": null,
"barcode": null
}
],
"number": 307,
"cancel_reason": null,
"owner_note": null,
"cancelled_at": null,
"closed_at": null,
"read_at": null,
"status": "open",
"payment_status": "pending",
"gateway_link": null,
"shipping_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2022-11-15T19:47:32+0000",
"default": false,
"floor": "No informado",
"id": 0,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2022-11-15T19:47:32+0000",
"zipcode": "0000",
"customs": null
},
"shipping_status": "unpacked",
"paid_at": null,
"client_details": {
"browser_ip": null,
"user_agent": null
},
"app_id": 2181
}
PUT /orders/{id}
Change an Order's attributes (just owner_note for now) and/or update an Order's status
PUT /orders/871310835
{
"owner_note": "Need to gift wrap this order",
"status": "closed"
}
HTTP/1.1 200 OK
{
"id": 871310835,
"token": "d928449fdd060fb7f3854c681923c28cfbccbcc1",
"store_id": 817495,
"contact_email": "john.doe@example.com",
"contact_name": "John Doe",
"contact_phone": "+55 11 99999-9999",
"contact_identification": null,
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"coupon": [],
"promotional_discount": {
"id": null,
"store_id": 817495,
"order_id": 871310835,
"created_at": "2022-11-15T19:49:48+0000",
"total_discount_amount": "0.00",
"contents": [],
"promotions_applied": []
},
"subtotal": "80.00",
"discount": "0.00",
"discount_coupon": "0.00",
"discount_gateway": "0.00",
"total": "80.00",
"total_usd": "80.00",
"checkout_enabled": true,
"weight": "0.000",
"currency": "USD",
"language": "es",
"gateway": "not-provided",
"gateway_id": null,
"gateway_name": "",
"shipping_pickup_type": "pickup",
"extra": {},
"storefront": "api",
"note": null,
"created_at": "2022-11-15T19:47:32+0000",
"updated_at": "2022-11-15T19:49:48+0000",
"completed_at": {
"date": "2022-11-15 19:47:32.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"payment_details": {
"method": null,
"credit_card_company": null,
"installments": 1
},
"attributes": [],
"customer": {
"id": 44769493,
"name": "John Doe",
"email": "john.doe@example.com",
"identification": null,
"phone": "+55 11 99999-9999",
"note": null,
"default_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
"addresses": [
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": null,
"created_at": "2020-09-11T18:06:09+0000",
"default": false,
"floor": "",
"id": 28900058,
"locality": "",
"name": "John Doe",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2020-09-11T18:06:09+0000",
"zipcode": "97475"
},
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-15T18:55:48+0000",
"default": false,
"floor": null,
"id": 52249003,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-15T18:55:48+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-24T14:01:01+0000",
"default": false,
"floor": null,
"id": 52781492,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-24T14:01:01+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
{
"address": "Fake Street",
"city": "Rosario",
"country": "AR",
"created_at": "2021-09-27T15:39:31+0000",
"default": false,
"floor": "",
"id": 52933588,
"locality": "",
"name": "John Doe",
"number": "123",
"phone": "+55 11 99999-9999",
"province": "Santa Fe",
"updated_at": "2021-09-27T15:39:31+0000",
"zipcode": "2000"
},
{
"address": null,
"city": null,
"country": "AR",
"created_at": "2021-09-27T15:43:15+0000",
"default": false,
"floor": null,
"id": 52933858,
"locality": null,
"name": "John Doe",
"number": null,
"phone": "+55 11 99999-9999",
"province": null,
"updated_at": "2021-09-27T15:43:15+0000",
"zipcode": null
}
],
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"extra": {},
"total_spent": "187.50",
"total_spent_currency": "USD",
"last_order_id": 871310835,
"active": false,
"first_interaction": "2022-11-15T19:47:32+0000",
"created_at": "2020-09-11T18:06:09+0000",
"updated_at": "2022-11-15T19:47:32+0000"
},
"products": [
{
"id": 1069079649,
"depth": "0.00",
"height": "0.00",
"name": "Producto B",
"price": "40.00",
"compare_at_price": "40.00",
"product_id": 63021345,
"image": {
"id": 0,
"product_id": 0,
"src": "https://d2r9epyceweg5n.cloudfront.net/assets/stores/img/no-photo-1024-1024.png",
"position": 0,
"alt": [],
"created_at": "2022-11-15T19:49:48+0000",
"updated_at": "2022-11-15T19:49:48+0000"
},
"quantity": 2,
"free_shipping": false,
"weight": "0.00",
"width": "0.00",
"variant_id": 194113141,
"variant_values": [],
"properties": [],
"sku": null,
"barcode": null
}
],
"number": 307,
"cancel_reason": null,
"owner_note": "Need to gift wrap this order",
"cancelled_at": null,
"closed_at": "2022-11-15T19:49:48+0000",
"read_at": null,
"status": "closed",
"payment_status": "paid",
"gateway_link": null,
"shipping_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2022-11-15T19:47:32+0000",
"default": false,
"floor": "No informado",
"id": 0,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2022-11-15T19:49:48+0000",
"zipcode": "0000",
"customs": null
},
"shipping_status": "unpacked",
"paid_at": "2022-11-15T19:48:39+0000",
"client_details": {
"browser_ip": null,
"user_agent": null
},
"app_id": 2181
}
Pay an Order
In fact, there is no action to pay an order. Orders are paid when sending a Transaction with status success, regardless of the event (sale or capture).
After payment, two order's attributes get modified: attribute payment_status receives "paid" and attribute paid_at receives the exact time the payment was processed.
{
"payment_status": "paid",
"paid_at": "2022-11-07T12:17:22+0000"
}
POST /orders/{id}/close
Close an Order
POST /orders/871310835/close
HTTP/1.1 200 OK
{
"id": 871310835,
"token": "d928449fdd060fb7f3854c681923c28cfbccbcc1",
"store_id": 817495,
"contact_email": "john.doe@example.com",
"contact_name": "John Doe",
"contact_phone": "+55 11 99999-9999",
"contact_identification": null,
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"coupon": [],
"promotional_discount": {
"id": null,
"store_id": 817495,
"order_id": 871310835,
"created_at": "2022-11-15T19:51:59+0000",
"total_discount_amount": "0.00",
"contents": [],
"promotions_applied": []
},
"subtotal": "80.00",
"discount": "0.00",
"discount_coupon": "0.00",
"discount_gateway": "0.00",
"total": "80.00",
"total_usd": "80.00",
"checkout_enabled": true,
"weight": "0.000",
"currency": "USD",
"language": "es",
"gateway": "not-provided",
"gateway_id": null,
"gateway_name": "",
"extra": {},
"storefront": "api",
"note": null,
"created_at": "2022-11-15T19:47:32+0000",
"updated_at": "2022-11-15T19:51:59+0000",
"completed_at": {
"date": "2022-11-15 19:47:32.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"payment_details": {
"method": null,
"credit_card_company": null,
"installments": 1
},
"attributes": [],
"customer": {
"id": 44769493,
"name": "John Doe",
"email": "john.doe@example.com",
"identification": null,
"phone": "+55 11 99999-9999",
"note": null,
"default_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
"addresses": [
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": null,
"created_at": "2020-09-11T18:06:09+0000",
"default": false,
"floor": "",
"id": 28900058,
"locality": "",
"name": "John Doe",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2020-09-11T18:06:09+0000",
"zipcode": "97475"
},
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-15T18:55:48+0000",
"default": false,
"floor": null,
"id": 52249003,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-15T18:55:48+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-24T14:01:01+0000",
"default": false,
"floor": null,
"id": 52781492,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-24T14:01:01+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
{
"address": "Fake Street",
"city": "Rosario",
"country": "AR",
"created_at": "2021-09-27T15:39:31+0000",
"default": false,
"floor": "",
"id": 52933588,
"locality": "",
"name": "John Doe",
"number": "123",
"phone": "+55 11 99999-9999",
"province": "Santa Fe",
"updated_at": "2021-09-27T15:39:31+0000",
"zipcode": "2000"
},
{
"address": null,
"city": null,
"country": "AR",
"created_at": "2021-09-27T15:43:15+0000",
"default": false,
"floor": null,
"id": 52933858,
"locality": null,
"name": "John Doe",
"number": null,
"phone": "+55 11 99999-9999",
"province": null,
"updated_at": "2021-09-27T15:43:15+0000",
"zipcode": null
}
],
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"extra": {},
"total_spent": "187.50",
"total_spent_currency": "USD",
"last_order_id": 871310835,
"active": false,
"first_interaction": "2022-11-15T19:47:32+0000",
"created_at": "2020-09-11T18:06:09+0000",
"updated_at": "2022-11-15T19:47:32+0000"
},
"products": [
{
"id": 1069079649,
"depth": "0.00",
"height": "0.00",
"name": "Producto B",
"price": "40.00",
"compare_at_price": "40.00",
"product_id": 63021345,
"image": {
"id": 0,
"product_id": 0,
"src": "https://d2r9epyceweg5n.cloudfront.net/assets/stores/img/no-photo-1024-1024.png",
"position": 0,
"alt": [],
"created_at": "2022-11-15T19:51:59+0000",
"updated_at": "2022-11-15T19:51:59+0000"
},
"quantity": 2,
"free_shipping": false,
"weight": "0.00",
"width": "0.00",
"variant_id": 194113141,
"variant_values": [],
"properties": [],
"sku": null,
"barcode": null
}
],
"number": 307,
"cancel_reason": null,
"owner_note": "Need to gift wrap this order",
"cancelled_at": null,
"closed_at": "2022-11-15T19:51:59+0000",
"read_at": null,
"status": "closed",
"payment_status": "paid",
"gateway_link": null,
"shipping_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2022-11-15T19:47:32+0000",
"default": false,
"floor": "No informado",
"id": 0,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2022-11-15T19:51:59+0000",
"zipcode": "0000",
"customs": null
},
"shipping_status": "unpacked",
"paid_at": "2022-11-15T19:48:39+0000",
"client_details": {
"browser_ip": null,
"user_agent": null
},
"app_id": 2181
}
POST /orders/{id}/open
Re-open a closed Order
POST /orders/871310835/open
HTTP/1.1 200 OK
{
"id": 871310835,
"token": "d928449fdd060fb7f3854c681923c28cfbccbcc1",
"store_id": 817495,
"contact_email": "john.doe@example.com",
"contact_name": "John Doe",
"contact_phone": "+55 11 99999-9999",
"contact_identification": null,
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"coupon": [],
"promotional_discount": {
"id": null,
"store_id": 817495,
"order_id": 871310835,
"created_at": "2022-11-15T19:52:37+0000",
"total_discount_amount": "0.00",
"contents": [],
"promotions_applied": []
},
"subtotal": "80.00",
"discount": "0.00",
"discount_coupon": "0.00",
"discount_gateway": "0.00",
"total": "80.00",
"total_usd": "80.00",
"checkout_enabled": true,
"weight": "0.000",
"currency": "USD",
"language": "es",
"gateway": "not-provided",
"gateway_id": null,
"gateway_name": "",
"extra": {},
"storefront": "api",
"note": null,
"created_at": "2022-11-15T19:47:32+0000",
"updated_at": "2022-11-15T19:52:37+0000",
"completed_at": {
"date": "2022-11-15 19:47:32.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"payment_details": {
"method": null,
"credit_card_company": null,
"installments": 1
},
"attributes": [],
"customer": {
"id": 44769493,
"name": "John Doe",
"email": "john.doe@example.com",
"identification": null,
"phone": "+55 11 99999-9999",
"note": null,
"default_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
"addresses": [
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": null,
"created_at": "2020-09-11T18:06:09+0000",
"default": false,
"floor": "",
"id": 28900058,
"locality": "",
"name": "John Doe",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2020-09-11T18:06:09+0000",
"zipcode": "97475"
},
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-15T18:55:48+0000",
"default": false,
"floor": null,
"id": 52249003,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-15T18:55:48+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-24T14:01:01+0000",
"default": false,
"floor": null,
"id": 52781492,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-24T14:01:01+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
{
"address": "Fake Street",
"city": "Rosario",
"country": "AR",
"created_at": "2021-09-27T15:39:31+0000",
"default": false,
"floor": "",
"id": 52933588,
"locality": "",
"name": "John Doe",
"number": "123",
"phone": "+55 11 99999-9999",
"province": "Santa Fe",
"updated_at": "2021-09-27T15:39:31+0000",
"zipcode": "2000"
},
{
"address": null,
"city": null,
"country": "AR",
"created_at": "2021-09-27T15:43:15+0000",
"default": false,
"floor": null,
"id": 52933858,
"locality": null,
"name": "John Doe",
"number": null,
"phone": "+55 11 99999-9999",
"province": null,
"updated_at": "2021-09-27T15:43:15+0000",
"zipcode": null
}
],
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"extra": {},
"total_spent": "187.50",
"total_spent_currency": "USD",
"last_order_id": 871310835,
"active": false,
"first_interaction": "2022-11-15T19:47:32+0000",
"created_at": "2020-09-11T18:06:09+0000",
"updated_at": "2022-11-15T19:47:32+0000"
},
"products": [
{
"id": 1069079649,
"depth": "0.00",
"height": "0.00",
"name": "Producto B",
"price": "40.00",
"compare_at_price": "40.00",
"product_id": 63021345,
"image": {
"id": 0,
"product_id": 0,
"src": "https://d2r9epyceweg5n.cloudfront.net/assets/stores/img/no-photo-1024-1024.png",
"position": 0,
"alt": [],
"created_at": "2022-11-15T19:52:37+0000",
"updated_at": "2022-11-15T19:52:37+0000"
},
"quantity": 2,
"free_shipping": false,
"weight": "0.00",
"width": "0.00",
"variant_id": 194113141,
"variant_values": [],
"properties": [],
"sku": null,
"barcode": null
}
],
"number": 307,
"cancel_reason": null,
"owner_note": "Need to gift wrap this order",
"cancelled_at": null,
"closed_at": null,
"read_at": null,
"status": "open",
"payment_status": "paid",
"gateway_link": null,
"shipping_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2022-11-15T19:47:32+0000",
"default": false,
"floor": "No informado",
"id": 0,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2022-11-15T19:52:37+0000",
"zipcode": "0000",
"customs": null
},
"shipping_status": "unpacked",
"paid_at": "2022-11-15T19:48:39+0000",
"client_details": {
"browser_ip": null,
"user_agent": null
},
"app_id": 2181
}
POST /orders/{id}/cancel
Cancel an Order
| Parameter | Explanation |
|---|---|
| reason | The reason for the order cancellation. Possible values are "customer", "inventory", "fraud" or "other" |
| Notify the customer of the cancellation (the default value is true) | |
| restock | Restock the store's products (the default value is true) |
POST /orders/871310835/cancel
HTTP/1.1 200 OK
{
"id": 871310835,
"token": "d928449fdd060fb7f3854c681923c28cfbccbcc1",
"store_id": 817495,
"contact_email": "john.doe@example.com",
"contact_name": "John Doe",
"contact_phone": "+55 11 99999-9999",
"contact_identification": null,
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"coupon": [],
"promotional_discount": {
"id": null,
"store_id": 817495,
"order_id": 871310835,
"created_at": "2022-11-15T19:52:37+0000",
"total_discount_amount": "0.00",
"contents": [],
"promotions_applied": []
},
"subtotal": "80.00",
"discount": "0.00",
"discount_coupon": "0.00",
"discount_gateway": "0.00",
"total": "80.00",
"total_usd": "80.00",
"checkout_enabled": true,
"weight": "0.000",
"currency": "USD",
"language": "es",
"gateway": "not-provided",
"gateway_id": null,
"gateway_name": "",
"extra": {},
"storefront": "api",
"note": null,
"created_at": "2022-11-15T19:47:32+0000",
"updated_at": "2022-11-15T19:52:37+0000",
"completed_at": {
"date": "2022-11-15 19:47:32.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"payment_details": {
"method": null,
"credit_card_company": null,
"installments": 1
},
"attributes": [],
"customer": {
"id": 44769493,
"name": "John Doe",
"email": "john.doe@example.com",
"identification": null,
"phone": "+55 11 99999-9999",
"note": null,
"default_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
"addresses": [
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": null,
"created_at": "2020-09-11T18:06:09+0000",
"default": false,
"floor": "",
"id": 28900058,
"locality": "",
"name": "John Doe",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2020-09-11T18:06:09+0000",
"zipcode": "97475"
},
{
"address": "Evergreen Terrace",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-15T18:55:48+0000",
"default": false,
"floor": null,
"id": 52249003,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-15T18:55:48+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "Springfield",
"country": "US",
"created_at": "2021-09-24T14:01:01+0000",
"default": false,
"floor": null,
"id": 52781492,
"locality": null,
"name": "No informado No informado",
"number": "742",
"phone": "5551230413",
"province": "Oregon",
"updated_at": "2021-09-24T14:01:01+0000",
"zipcode": "97475"
},
{
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2021-09-24T14:02:57+0000",
"default": true,
"floor": "No informado",
"id": 52781637,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2021-09-24T14:02:57+0000",
"zipcode": "0000"
},
{
"address": "Fake Street",
"city": "Rosario",
"country": "AR",
"created_at": "2021-09-27T15:39:31+0000",
"default": false,
"floor": "",
"id": 52933588,
"locality": "",
"name": "John Doe",
"number": "123",
"phone": "+55 11 99999-9999",
"province": "Santa Fe",
"updated_at": "2021-09-27T15:39:31+0000",
"zipcode": "2000"
},
{
"address": null,
"city": null,
"country": "AR",
"created_at": "2021-09-27T15:43:15+0000",
"default": false,
"floor": null,
"id": 52933858,
"locality": null,
"name": "John Doe",
"number": null,
"phone": "+55 11 99999-9999",
"province": null,
"updated_at": "2021-09-27T15:43:15+0000",
"zipcode": null
}
],
"billing_name": "John",
"billing_phone": "51230413",
"billing_address": "Evergreen Terrace",
"billing_number": "742",
"billing_floor": "Apartment 8",
"billing_locality": "Bronx",
"billing_zipcode": "10451",
"billing_city": "New York",
"billing_province": "New York",
"billing_country": "US",
"extra": {},
"total_spent": "187.50",
"total_spent_currency": "USD",
"last_order_id": 871310835,
"active": false,
"first_interaction": "2022-11-15T19:47:32+0000",
"created_at": "2020-09-11T18:06:09+0000",
"updated_at": "2022-11-15T19:47:32+0000"
},
"products": [
{
"id": 1069079649,
"depth": "0.00",
"height": "0.00",
"name": "Producto B",
"price": "40.00",
"compare_at_price": "40.00",
"product_id": 63021345,
"image": {
"id": 0,
"product_id": 0,
"src": "https://d2r9epyceweg5n.cloudfront.net/assets/stores/img/no-photo-1024-1024.png",
"position": 0,
"alt": [],
"created_at": "2022-11-15T19:52:37+0000",
"updated_at": "2022-11-15T19:52:37+0000"
},
"quantity": 2,
"free_shipping": false,
"weight": "0.00",
"width": "0.00",
"variant_id": 194113141,
"variant_values": [],
"properties": [],
"sku": null,
"barcode": null
}
],
"number": 307,
"cancel_reason": "other",
"owner_note": "Need to gift wrap this order",
"cancelled_at": "2022-11-15T19:57:42+0000",
"closed_at": null,
"read_at": null,
"status": "cancelled",
"payment_status": "paid",
"gateway_link": null,
"shipping_address": {
"address": "No informado",
"city": "No informado",
"country": "AR",
"created_at": "2022-11-15T19:47:32+0000",
"default": false,
"floor": "No informado",
"id": 0,
"locality": "No informado",
"name": "No informado No informado",
"number": "No informado",
"phone": "No informado",
"province": "No informado",
"updated_at": "2022-11-15T19:52:37+0000",
"zipcode": "0000",
"customs": null
},
"shipping_status": "unpacked",
"paid_at": "2022-11-15T19:48:39+0000",
"client_details": {
"browser_ip": null,
"user_agent": null
},
"app_id": 2181
}
Invoices (e.g. NFe in Brazil)
We currently do not offer an Invoice API, but there are many apps which need to read and/or write
invoice information. The way to achieve this is using Metafields.
The advantage of using Metafields is that a certain app could generate the invoice and another app can read it.
Let's take a real Brazilian example: an ERP can generate the nota fiscal (NFe) and a Shipping Carrier can use that
NFe to fulfill a shipment.
Create an invoice
An Order may have more than one invoice, so we will have a Metafield that holds a list of invoices. It's the responsbility of invoice producers to make sure this format is maintained when new invoices are added.
When adding a new invoice you have to append it to the list of NFEs adding both the NFe key (generated when created) and the link to the NFe XML and an optional fulfillment_order_id specifying the Fulfillment Order the NFe applies to. The value of the metafields holds a json encoded string representation of the NFEs' list; the list is an array of object that have key and link properties. The value of owner_id should hold the Order id.
Example: let's say we want to add a new NFe with key 55555555555555555555555555555 and link http://nfe.com.br/nsaasb assigned to the Fulfillment Order with id 01FHZXHK8PTP9FVK99Z66GXASS.
To make sure other apps can read the invoice you create, please use this example as-is.
First we have to check if the NFe metafield already exists.
GET /metafields/orders?per_page=1&owner_id=ORDER_ID&namespace=nfe&key=list&fields=id,value
This will return an empty array if the NFe metafield does not exist.
HTTP/1.1 200 OK
[]
or an aray with one object with the id and value in case it exists.
HTTP/1.1 200 OK
[
{
"id": 12345,
"value": "[{\"key\": \"44444444444444444444444444444\", \"link\": \"http://nfe.com.br/nsaasa\", \"fulfillment_order_id\": \"01FHZXHK8PTP9FVK99Z66GXASS\"}]",
}
]
If the NFe list metafield does not exist
We need to create a new metafield. Please note that value is a JSON encoded string so for it to be valid JSON all double quotes must be escaped.
POST /metafields
{
"namespace": "nfe",
"key": "list",
"value": "[{\"key\": \"55555555555555555555555555555\", \"link\": \"http://nfe.com.br/nsaasb\", \"fulfillment_order_id\": \"01FHZXHK8PTP9FVK99Z66GXASS\"}]",
"description": "Lista de NFes",
"owner_resource": "Order",
"owner_id": 12345678
}
HTTP/1.1 201 Created
{
"id": 12345,
"namespace": "nfe",
"key": "link",
"value": "[{\"key\": \"55555555555555555555555555555\", link: \"http://nfe.com.br/nsaasb\", \"fulfillment_order_id\": \"01FHZXHK8PTP9FVK99Z66GXASS\"}]",
"description": "Lista de NFes",
"owner_resource": "Order",
"owner_id": 12345678,
"created_at": "2015-01-02 20:27:51",
"updated_at": "2015-01-02 20:27:51",
"deleted_at": null
}
If the NFe list metafield already existed
We now have to append our NFe to the existing array and update the metafield using the metafield id.
PUT /metafields/METAFIELD_ID
{
"value": "[{\"key\": \"44444444444444444444444444444\", \"link\": \"http://nfe.com.br/nsaasa\", \"fulfillment_order_id\": \"01FHZXHK8PTP9FVK99Z66GXASS\"}, {\"key\": \"55555555555555555555555555555\", \"link\": \"http://nfe.com.br/nsaasb\", \"fulfillment_order_id\": \"01ARZ3NDEKTSV4RRFFQ69G5FAV\"}]"
}
HTTP/1.1 200 OK
{
"id": 12345,
"namespace": "nfe",
"key": "list",
"value": "[{\"key\": \"44444444444444444444444444444\", \"link\": \"http://nfe.com.br/nsaasa\", \"fulfillment_order_id\": \"01FHZXHK8PTP9FVK99Z66GXASS\"}, {\"key\": \"55555555555555555555555555555\", \"link\": \"http://nfe.com.br/nsaasb\", \"fulfillment_order_id\": \"01ARZ3NDEKTSV4RRFFQ69G5FAV\"}]",
"description": "Lista de NFes",
"owner_resource": "Order",
"owner_id": 12345678,
"created_at": "2015-01-02 20:27:51",
"updated_at": "2015-01-05 18:15:40",
"deleted_at": null
}
Please take into account that JSON arrays do not allow trailing commas.
Read an invoice
To read an invoice we need to search for the previously created metafield holding the invoice.
GET /metafields/orders?per_page=1&owner_id=ORDER_ID&namespace=nfe&key=list&fields=value
HTTP/1.1 200 OK
[
{
"value": "[{\"key\": \"44444444444444444444444444444\", \"link\": \"http://nfe.com.br/nsaasa\", \"fulfillment_order_id\": \"01FHZXHK8PTP9FVK99Z66GXASS\"}, {\"key\": \"55555555555555555555555555555\", \"link\": \"http://nfe.com.br/nsaasb\", \"fulfillment_order_id\": \"01ARZ3NDEKTSV4RRFFQ69G5FAV\"}]",
}
]
You can then JSON decode the value to access the list of NFEs.
Note: you can still use the old method of sending the NFe key and url as two separate metafields, but we recommend migrating to this new method as it is now the preferred method for NFe consumers as it allows to receive multiple NFes supporting orders with multiple fulfillments.
FAQ
What are our recommendations on best practices for retrieving orders information?
We at Tiendanube are a platform concerned with balancing cost x resilience x security of our APIs, so we recommend following some practices that we consider healthy when interacting with orders.
General:
- Rate Limit: in order to control the incoming traffic from the API
- Pagination: to make sure responses are easier to handle
Import:
- Loop calls: avoid frequent loop calls - many times these calls are unnecessary as the resource has not changed and the response will be the same as before.
- Import by period: to avoid loop calls, you can use import by period, which consists of defining time intervals for imports. Ex: first import takes orders from 01/01/2023 to 01/03/2023, the second import takes orders from 01/04/2023 to 01/06/2023 and so on. For this case, you can use the parameters
created_at_minandcreated_at_maxto import orders by period.
Webhooks:
- Import orders using Webhooks: an even better alternative than importing by period is to create orders webhooks to be notified as soon as there is an interaction with a resource (create, retrieve, update, delete).
- Use Specific Webhooks: there are all kinds of Webhooks. Therefore, we encourage our partners to only use those that apply to their use case. Example: if you need to know when an order was packed, create a webhook for
order/packedand notorder/updated, which in turn notifies the user of any changes to the order. Creating theorder/updatedwebhook would generate several non-applicable notifications to the partner, which in turn would make several unnecessary queries to the Tiendanube API. - Order/paid Webhook: the
order/paidwebhook notifies the partner that the order has been paid. After payment, two order's attributes get modified: attributepayment_statusreceives "paid" and attributepaid_atreceives the exact time the payment was processed. Therefore, it is not necessary to send a request to Tiendanube, since thegatewayfield (which contains the payment method used by the customer) will already have been filled in at the time of creating the order and can be obtained if the partner has created the webhook fororder/created.
Orders placed via API do not update stock?
The Tiendanube API has the ability to create orders without reserving stock. It depends on the inventory behavior parameter. If it's claim, it reserves stock. If it's bypass skips the stock reserve.
Things to take into account when implementing a Subscription App
Usually a Subscription App works this way: a consumer places an Order for the first time and the subsequent orders are created through API. The first order will be created without any problems or lack of information, that is, order will appear as paid on Tiendanube's Admin and you will be able to see information regarding transactions (external_id and external_url). That's because the order was created through Tiendanube's Checkout by selecting the payment provider.
On the other hand, because the subsequent orders are created through API, the Merchant won't be able to see which payment processor created the order. Besides that, even though the Partners tries to create transaction to provide more info (external_id and external_url) on the order, the transaction won't be read by order since it was created through API, as mentioned before.
Despite this "limitations", we recommend creating the subsequent order as paid and put more info (external_id and external_url) on a field called owner_note, which is visible to the Merchant. This way, we guarantee the Merchant will see the Order as paid to perform the next steps (packing and shipping) and will also be able to see more details about the payment processing directly through the order detail.
Only Argentinian stores: How to know when the buyer requested a 'Factura A' during checkout?
In checkout, we have the following checkbox available:
When it is checked, the following fields are sent with information:- billing_customer_type: "company"
billing_business_name: "{value_of_business_name}"billing_document_type: "cuit"
If it is not checked, those fields are sent as null.