Order
An order is created when a customer completes the checkout process. Orders also can be created through the API.
📢 Important 📢
A new Order API with support for multi inventory is currently being rolled out to every merchant.
For any new development, we strongly recommend you to use the new version. Please contact us to activate this new version in your stores if needed.
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. |
| shipping | The shipping method used |
| shipping_pickup_type | "ship" if the order is going to be shipped; "pickup" if it's going to be picked up from a store branch |
| shipping_store_branch_name | If order is going to be picked up, shows the store branch name |
| 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_carrier_name | The shipping carrier name. If shipping method is custom, then null. |
| shipping_address | The customer's shipping address where the order will be shipped |
| shipping_tracking_number | The shipping tracking number for the order. This may be null if not available |
| shipping_min_days | The minimum number of weekdays needed for the order to be delivered |
| shipping_max_days | The maximum number of weekdays needed for the order to be delivered |
| shipping_cost_owner | The shipping cost the store owner has to pay to the shipping company. |
| shipping_cost_customer | The shipping cost the customer has to pay to the store owner. |
| shipping_option | The shipping option chosen by the customer during the checkout process. |
| shipping_option_code | The shipping option code selected by the consumers. |
| shipping_option_reference | The shipping option reference provided by a custom shipping carrier during the checkout process. |
| shipping_pickup_details | The shipping pickup details (address and/or business hours) of the selected pickup point. |
| shipping_tracking_url | The shipping tracking URL where the customer can check for the shipment status. |
| 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 |
| shipping_suboption | If shipping_pickup_type is "pickup", then object that contains ID of the pickup option (for internal use). Otherwise, empty array. |
| 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", "abandoned", "refunded" or "voided" |
| shipping_status | Order's shipping status. Possible values are "unpacked", "fulfilled" (means "shipped") or "unfulfilled" (means "unshipped") |
| next_action | Next available operation in the orders flow |
| payment_details | A JSON object containing payment details. |
| shipped_at | Date when the Order was shipped in ISO 8601 format |
| 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 |
| landing_url | URL of the landing page that led to the purchase. If the order was created via API by an app, then null. |
| client_details | Customer details for analytics. |
| app_id | If the order was created via API by an app, ID of the app. Otherwise, null. |
Property next_action can take one of the following values:
- noop: no action to take
- close: order should be closed
- waiting_ipn: we are waiting for the gateway to update us on the order status, the seller just needs to wait
- waiting_manual_confirmation: we are waiting for the seller to confirm the transaction
- waiting_packing: we are waiting for the seller to pack the order items
- waiting_pickup: we are waiting for the fulfillment provider to pick up the order
- waiting_client_pickup: we are waiting for the buyer to pick up the order (he shipped it to a seller's B&M store)
- waiting_shipment: we are waiting for the seller to ship the order
The products field has the following contents:
| Property | Explanation |
|---|---|
| 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. |
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. |
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 | The unique numeric identifier for the promotional discount. |
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 |
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",
"shipping_min_days": null,
"shipping_max_days": null,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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",
"shipping": "table",
"shipping_option": "Envio Personalizado 1",
"shipping_option_code": "table_6103303",
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": null,
"shipping_tracking_url": null,
"shipping_store_branch_name": null,
"shipping_pickup_type": "ship",
"shipping_suboption": [],
"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"
},
"next_action": "waiting_manual_confirmation",
"payment_details": {
"method": "custom",
"credit_card_company": null,
"installments": 1
},
"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_carrier_name": 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",
"shipped_at": null,
"paid_at": null,
"landing_url": "http://www.example.com?source=abc",
"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?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
| Parameter | Explanation |
|---|---|
| fields | Comma-separated list of fields to include in the response |
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",
"shipping_min_days": null,
"shipping_max_days": null,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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",
"shipping": "table",
"shipping_option": "Envio Personalizado 1",
"shipping_option_code": "table_6103303",
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": null,
"shipping_tracking_url": null,
"shipping_store_branch_name": null,
"shipping_pickup_type": "ship",
"shipping_suboption": [],
"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"
},
"next_action": "waiting_manual_confirmation",
"payment_details": {
"method": "custom",
"credit_card_company": null,
"installments": 1
},
"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_carrier_name": 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",
"shipped_at": null,
"paid_at": null,
"landing_url": "http://www.example.com?source=abc",
"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
}
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 paid. | 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 |
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 |
|---|---|---|---|
| name | The customer's full 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. | 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 |
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,
"shipping_min_days": 0,
"shipping_max_days": 0,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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": "",
"shipping": "not-provided",
"shipping_option": "No informado",
"shipping_option_code": null,
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": null,
"shipping_tracking_url": null,
"shipping_store_branch_name": null,
"shipping_pickup_type": "pickup",
"shipping_suboption": [],
"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"
},
"next_action": "waiting_manual_confirmation",
"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_carrier_name": 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",
"shipped_at": null,
"paid_at": null,
"landing_url": 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,
"shipping_min_days": 0,
"shipping_max_days": 0,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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": "not-provided",
"shipping_option": "No informado",
"shipping_option_code": null,
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": null,
"shipping_tracking_url": null,
"shipping_store_branch_name": null,
"shipping_pickup_type": "pickup",
"shipping_suboption": [],
"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"
},
"next_action": "noop",
"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_carrier_name": 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",
"shipped_at": null,
"paid_at": "2022-11-15T19:48:39+0000",
"landing_url": null,
"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,
"shipping_min_days": 0,
"shipping_max_days": 0,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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": "",
"shipping": "not-provided",
"shipping_option": "No informado",
"shipping_option_code": null,
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": null,
"shipping_tracking_url": null,
"shipping_store_branch_name": null,
"shipping_pickup_type": "pickup",
"shipping_suboption": [],
"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"
},
"next_action": "noop",
"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_carrier_name": 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",
"shipped_at": null,
"paid_at": "2022-11-15T19:48:39+0000",
"landing_url": null,
"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,
"shipping_min_days": 0,
"shipping_max_days": 0,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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": "",
"shipping": "not-provided",
"shipping_option": "No informado",
"shipping_option_code": null,
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": null,
"shipping_tracking_url": null,
"shipping_store_branch_name": null,
"shipping_pickup_type": "pickup",
"shipping_suboption": [],
"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"
},
"next_action": "waiting_packing",
"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_carrier_name": 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",
"shipped_at": null,
"paid_at": "2022-11-15T19:48:39+0000",
"landing_url": null,
"client_details": {
"browser_ip": null,
"user_agent": null
},
"app_id": 2181
}
POST /orders/{id}/pack​
Pack an Order
POST /orders/871310835/pack​
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,
"shipping_min_days": 0,
"shipping_max_days": 0,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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": "",
"shipping": "not-provided",
"shipping_option": "No informado",
"shipping_option_code": null,
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": null,
"shipping_tracking_url": null,
"shipping_store_branch_name": null,
"shipping_pickup_type": "pickup",
"shipping_suboption": [],
"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"
},
"next_action": "waiting_packing",
"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_carrier_name": 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": "packed",
"shipped_at": null,
"paid_at": "2022-11-15T19:48:39+0000",
"landing_url": null,
"client_details": {
"browser_ip": null,
"user_agent": null
},
"app_id": 2181
}
POST /orders/{id}/fulfill​
Fulfill an Order
| Parameter | Explanation |
|---|---|
| shipping_tracking_number | Shipment's tracking number provided by the shipping company |
| shipping_tracking_url | Shipment's tracking URL provided by the shipping company |
| notify_customer | Notify the customer about the fulfillment (the default value is true) |
POST /orders/871310835/fulfill​
{
"shipping_tracking_number": "ABC1234",
"shipping_tracking_url": "https://shipping.com/tracking/ABC1234",
"notify_customer": true
}
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,
"shipping_min_days": 0,
"shipping_max_days": 0,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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": "",
"shipping": "not-provided",
"shipping_option": "No informado",
"shipping_option_code": null,
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": "ABC1234",
"shipping_tracking_url": "https://shipping.com/tracking/ABC1234",
"shipping_store_branch_name": null,
"shipping_pickup_type": "pickup",
"shipping_suboption": [],
"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"
},
"next_action": "waiting_packing",
"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_carrier_name": 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",
"shipped_at": null,
"paid_at": "2022-11-15T19:48:39+0000",
"landing_url": null,
"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,
"shipping_min_days": 0,
"shipping_max_days": 0,
"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",
"shipping_cost_owner": "0.00",
"shipping_cost_customer": "0.00",
"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": "",
"shipping": "not-provided",
"shipping_option": "No informado",
"shipping_option_code": null,
"shipping_option_reference": null,
"shipping_pickup_details": null,
"shipping_tracking_number": "ABC1234",
"shipping_tracking_url": "https://shipping.com/tracking/ABC1234",
"shipping_store_branch_name": null,
"shipping_pickup_type": "pickup",
"shipping_suboption": [],
"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"
},
"next_action": "waiting_packing",
"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_carrier_name": 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",
"shipped_at": null,
"paid_at": "2022-11-15T19:48:39+0000",
"landing_url": null,
"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.