# Carrinho, pedidos e produtos

> Consulte e atualize produtos, envie produtos, mexa no carrinho e mude o status, a entrega e o pagamento dos pedidos pela API, com valores em centavos.

Endereço: https://docs.nextags.com.br/guias/carrinho-e-pedidos/
Tipo: Guia

Atualizado em: 26/10/2026

O E-commerce da NexTags vende pela conversa: o contato vê os produtos, monta o carrinho e fecha o pedido. Pela API, o seu sistema mantém preço e estoque em dia, mexe no carrinho do contato e acompanha o pedido até a entrega e o pagamento. Atenção às unidades: o preço do produto vai em reais, e os totais do carrinho e do pedido, em centavos.

**Antes de começar**

- A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/).
- Os produtos cadastrados em **Ferramentas** › **Ecommerce**. Veja [Cadastrar produtos](https://help.nextags.com.br/tutoriais/ecommerce/cadastrar-produtos/).
- Os IDs do produto, do contato e do pedido. A API não lista produtos nem pedidos: veja onde achar cada ID em [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/).

## Passo a passo

### Passo 1: Consulte o produto

Use [Consultar produto](https://docs.nextags.com.br/referencia/ecommerce/consultar-produto/):

**Consultar produto**

```bash
curl "https://app.nextagsai.com.br/api/products/6001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/products/6001', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/products/6001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/products/6001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

```json
{
  "id": 6001,
  "name": "Bolo de chocolate",
  "price": 89.9,
  "sale_price": 79.9,
  "category_id": 6101,
  "category_name": "Bolos",
  "stock": 12,
  "short_description": "Serve 12 pessoas",
  "image": "https://seusistema.exemplo.com.br/img/bolo-de-chocolate.jpg",
  "created_at": "2026-10-01 12:00:00"
}
```

O `price` está em reais: `89.9` é R$ 89,90.

### Passo 2: Atualize o preço, o estoque e se está à venda

Use [Atualizar produto](https://docs.nextags.com.br/referencia/ecommerce/atualizar-produto/). Mande só o que muda: `price`, `stock` e `active` (se os contatos podem comprar o produto).

**Atualizar produto**

```bash
curl -X POST "https://app.nextagsai.com.br/api/products/6001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 94.9,
    "stock": 20,
    "active": true
  }'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/products/6001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    price: 94.9,
    stock: 20,
    active: true,
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/products/6001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "price": 94.9,
        "stock": 20,
        "active": True,
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/products/6001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'price' => 94.9,
        'stock' => 20,
        'active' => true,
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta é `{"success": true, "updated": true}`. Confira na lista de **Produtos** que o preço ficou R$ 94,90.

### Passo 3: Envie produtos ao contato

Use [Enviar produtos ao contato](https://docs.nextags.com.br/referencia/ecommerce/enviar-produtos-ao-contato/). O `product_id` aceita um ID, uma lista de IDs ou IDs separados por vírgula:

**Enviar produtos ao contato**

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send/products" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": [
      6001,
      6002
    ]
  }'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/products', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    product_id: [6001, 6002],
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/send/products",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "product_id": [6001, 6002],
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/send/products');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'product_id' => [6001, 6002],
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

O contrato não descreve a resposta: confira o código HTTP e a conversa na **Caixa de Entrada**. Como toda mensagem, o envio segue a janela de 24 horas do WhatsApp. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/).

### Passo 4: Ponha um produto no carrinho

Use [Adicionar produto ao carrinho](https://docs.nextags.com.br/referencia/ecommerce/adicionar-produto-ao-carrinho/). Esta chamada recebe formulário, com a quantidade em `quantity`:

**Adicionar produto ao carrinho**

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'quantity=2'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
  body: new URLSearchParams({
    quantity: 2,
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    data={
        "quantity": 2,
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'quantity' => 2,
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta é `{"success": true}`.

### Passo 5: Consulte o carrinho

Use [Consultar carrinho](https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho/):

**Consultar carrinho**

```bash
curl "https://app.nextagsai.com.br/api/contacts/123456789/cart" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/123456789/cart",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/cart');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta (aqui, resumida) traz o `order_id`, os totais em centavos e os itens, com o `price` de cada item em reais:

```json
{
  "order_id": "PED-1001",
  "user_id": 123456789,
  "currency": "BRL",
  "total": 17980,
  "subtotal": 17980,
  "total_items": 2,
  "coupon_discount": 0,
  "coupon": "",
  "line_items": [
    {"id": 6001, "name": "Bolo de chocolate", "price": 89.9, "amount": 2}
  ]
}
```

| Campo | Unidade | No exemplo |
|---|---|---|
| `total`, `subtotal`, `coupon_discount` | Centavos | `17980` = R$ 179,80 |
| `line_items[].price` | Reais | `89.9` = R$ 89,90 |
| `line_items[].amount` | Quantidade | `2` |

### Passo 6: Tire um produto ou esvazie o carrinho

Para tirar um produto, use [Remover produto do carrinho](https://docs.nextags.com.br/referencia/ecommerce/remover-produto-do-carrinho/):

**Remover produto do carrinho**

```bash
curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001', {
  method: 'DELETE',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.delete(
    "https://app.nextagsai.com.br/api/contacts/123456789/cart/6001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

Para tirar tudo, use [Esvaziar carrinho](https://docs.nextags.com.br/referencia/ecommerce/esvaziar-carrinho/):

**Esvaziar carrinho**

```bash
curl -X DELETE "https://app.nextagsai.com.br/api/contacts/123456789/cart" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart', {
  method: 'DELETE',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.delete(
    "https://app.nextagsai.com.br/api/contacts/123456789/cart",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/cart');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

As duas respondem `{"success": true}`.

### Passo 7: Consulte o pedido

Use [Consultar pedido](https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido/), com o ID do pedido. O ID é texto: mande do jeito que veio.

**Consultar pedido**

```bash
curl "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001', {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta tem o mesmo formato do carrinho, com os valores em centavos.

### Passo 8: Mude o status e a entrega

Use [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/). O `status` aceita quatro valores, e os dados de entrega e a nota são opcionais:

**Alterar pedido**

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 7,
    "name": "Ana Souza",
    "phone": "5511988776655",
    "city": "São Paulo",
    "state": "SP",
    "zip_code": "01310-100",
    "address": "Avenida Paulista, 1000",
    "note": "Saiu para entrega."
  }'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    status: 7,
    name: 'Ana Souza',
    phone: '5511988776655',
    city: 'São Paulo',
    state: 'SP',
    zip_code: '01310-100',
    address: 'Avenida Paulista, 1000',
    note: 'Saiu para entrega.',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "status": 7,
        "name": "Ana Souza",
        "phone": "5511988776655",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01310-100",
        "address": "Avenida Paulista, 1000",
        "note": "Saiu para entrega.",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'status' => 7,
        'name' => 'Ana Souza',
        'phone' => '5511988776655',
        'city' => 'São Paulo',
        'state' => 'SP',
        'zip_code' => '01310-100',
        'address' => 'Avenida Paulista, 1000',
        'note' => 'Saiu para entrega.',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

| `status` | No contrato | Na tela |
|---|---|---|
| `6` | Em processamento | **Aceito** |
| `7` | Enviado | **Entregando** |
| `10` | Concluído | **Concluído** |
| `13` | Cancelado | **Cancelado** |

Os dados de entrega são `name`, `phone`, `email`, `country`, `state`, `city`, `zip_code`, `address`, `street_1` e `street_2`, e `note` guarda uma nota do pedido. A resposta é `{"success": true}`.

### Passo 9: Marque o pedido como pago

Use [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/). Esta chamada recebe formulário, com o valor pago em centavos em `amount_received`:

**Marcar pedido como pago**

```bash
curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'amount_received=17980'
```
```javascript
const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
  body: new URLSearchParams({
    amount_received: 17980,
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
```
```python
import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    data={
        "amount_received": 17980,
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())
```
```php
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'amount_received' => 17980,
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
```

A resposta é `{"success": true}`. O valor não pode ser menor que o total do pedido.

## Pronto: como conferir

- [Consultar pedido](https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido/) mostra o pedido com os valores certos.
- Na **Caixa de Entrada**, o painel do contato lista os **Pedidos**, com o valor, a data e a situação. Veja [Carrinho e pedidos na conversa](https://help.nextags.com.br/tutoriais/ecommerce/carrinho-e-pedidos/).

## Se não funcionou

### 401 com "No valid API key provided."

A chave não chegou ou não vale. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/).

### Alterar pedido: 400 com "Order status must be 6, 7, 10, or 13"

O `status` não é um dos quatro aceitos. Use `6`, `7`, `10` ou `13`, como número.

### Alterar pedido: 402

O pedido já está nesse status. Consulte o pedido antes e só mande o `status` quando ele mudar.

### Marcar pedido como pago: 400

O `amount_received` é menor que o total do pedido. Confira se mandou em centavos: R$ 179,80 é `17980`, não `179.80`.

### Marcar pedido como pago: 402

O pagamento não foi concluído. O contrato descreve assim: o contato recebe uma mensagem no Messenger com o motivo da falha do checkout. Consulte o pedido e a conversa do contato para entender o caso.

### 404 com "The order ID doesn't existe"

O ID do pedido não existe para esse contato. Confira o `order_id` e o ID do contato: os dois vão no caminho.

### O preço do produto ficou cem vezes maior

O `price` do produto vai em reais, não em centavos. Para R$ 94,90, mande `94.9`.

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
Leia https://docs.nextags.com.br/guias/carrinho-e-pedidos.md.

Quero manter o E-commerce da NexTags em dia com [o seu sistema, por exemplo: o ERP da loja]: atualizar preço e estoque dos produtos quando mudarem, mudar o status do pedido quando [eventos de entrega] e marcar como pago quando [o pagamento for aprovado]. Escreva, em [linguagem], o código com a conversão certa de unidades (preço do produto em reais; totais e valor pago em centavos) e o tratamento dos erros 400, 402 e 404. A chave vem da variável de ambiente NEXTAGS_API_KEY.
```