Consulte as vendas feitas no checkout, com itens, variantes e valores em centavos.

Visão Geral

A API de Pedidos lista as vendas feitas no checkout do Plasma. Cada pedido traz os itens com a variante comprada, os valores em centavos, o checkoutToken do link que o originou e o metadata que você mandou ao criar o link.

É o mesmo formato do data dos webhooks de pedido. Use a API para conferir uma venda, reconciliar ou montar relatórios; use os webhooks para reagir na hora.

A API de Pedidos é só leitura. Pedido nasce no checkout, e o status de pagamento vem do gateway. Criar ou alterar pedido pela API (POST, PATCH) responde 410 ENDPOINT_GONE.

Endpoints

Método	Endpoint	Descrição
`GET`	`/api/sdk/orders`	Listar vendas, com cursor
`GET`	`/api/sdk/orders/:id`	Buscar uma venda pelo id ou pelo número do pedido

Listar Pedidos

GET /api/sdk/orders

Parâmetros de Query

Parâmetro	Tipo	Descrição
`limit`	`number`	Máximo de itens (1 a 100, padrão: 50)
`cursor`	`string`	Cursor para paginação (`pagination.nextCursor`)
`paymentStatus`	`string`	Filtrar por status de pagamento (ver tabela abaixo)
`status`	`string`	Filtrar pelo status do pedido
`fulfillmentStatus`	`string`	`unfulfilled` ou `fulfilled`
`checkoutToken`	`string`	O pedido criado a partir de um link de checkout
`customerEmail`	`string`	O e-mail inteiro do comprador, sem diferenciar maiúsculas (não busca por trecho)
`orderNumber`	`string`	Buscar pelo número do pedido
`search`	`string`	Busca por trecho do número, do e-mail ou do nome
`dateFrom`	`string`	Data inicial (ISO 8601)
`dateTo`	`string`	Data final (ISO 8601)
`sortBy`	`string`	`createdAt`, `updatedAt`, `totalCents` ou `orderNumber`
`sortOrder`	`string`	`asc` ou `desc` (padrão: `desc`)

Exemplo

curl -X GET "https://api.plasmacheckout.com/api/sdk/orders?paymentStatus=paid&limit=10" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

// Vendas pagas
const { data: vendas, pagination } = await plasma.orders.list({ paymentStatus: 'paid', limit: 10 });

// A venda de um carrinho seu, pelo token guardado ao criar o link
const { data: doCarrinho } = await plasma.orders.list({ checkoutToken: tokenGuardado });

import requests

response = requests.get(
    'https://api.plasmacheckout.com/api/sdk/orders',
    headers={
        'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
        'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx'
    },
    params={'paymentStatus': 'paid', 'limit': 10}
)

data = response.json()
print(data['data'])
print(data['pagination'])

Resposta

{
  "data": [
    {
      "id": "cmu9pedido0001",
      "orderNumber": "P-7K2M9Q",
      "checkoutToken": "c08b6109-4c32-46ac-9a8a-bb72b7ec71de",
      "parentOrderId": null,
      "status": "open",
      "paymentStatus": "paid",
      "fulfillmentStatus": "unfulfilled",
      "customer": {
        "email": "cliente@email.com",
        "name": "João Silva",
        "phone": "+5511999999999"
      },
      "items": [
        {
          "productId": "cmu1splash0001",
          "variantId": "cmu1var10ml",
          "title": "Body Splash Lavanda",
          "variantTitle": "10ml",
          "sku": "BSL-10",
          "quantity": 2,
          "priceCents": 4990,
          "totalCents": 9980,
          "image": "https://cdn.minhaloja.com/lavanda.jpg",
          "kind": "item"
        }
      ],
      "totals": {
        "subtotalCents": 9980,
        "shippingCents": 1500,
        "discountCents": 0,
        "taxCents": 0,
        "totalCents": 11480
      },
      "currency": "BRL",
      "payment": {
        "method": "pix",
        "paidAt": "2026-10-04T12:00:00.000Z",
        "refundedAt": null
      },
      "shippingAddress": { "city": "São Paulo", "zip": "01001000" },
      "billingAddress": null,
      "metadata": { "pedidoDaLoja": "Y-123" },
      "createdAt": "2026-10-04T11:58:12.000Z",
      "updatedAt": "2026-10-04T12:00:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cmu9pedido0001",
    "count": 10,
    "total": 250
  },
  "filters": {
    "status": null,
    "paymentStatus": "paid",
    "fulfillmentStatus": null,
    "customerEmail": null,
    "checkoutToken": null,
    "dateFrom": null,
    "dateTo": null
  }
}

Buscar Pedido

GET /api/sdk/orders/:id

Aceita o id ou o número do pedido (orderNumber). Pedido de outra loja devolve 404.

curl -X GET "https://api.plasmacheckout.com/api/sdk/orders/P-7K2M9Q" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

const { data: pedido } = await plasma.orders.get('P-7K2M9Q');

O Pedido

Campo	Descrição
`id`	Id do pedido no Plasma
`orderNumber`	Número do pedido, o que o comprador vê
`checkoutToken`	O token do link de checkout que originou o pedido. Nulo em pedido que não nasceu de um link
`parentOrderId`	O pedido de origem, quando este é um upsell aceito depois do pagamento
`paymentStatus`	Status do pagamento (ver tabela)
`items`	As linhas do pedido
`totals`	`subtotalCents`, `shippingCents`, `discountCents`, `taxCents` e `totalCents`
`payment`	`method` (`pix`, `credit_card` ou `boleto`), `paidAt` e `refundedAt`
`metadata`	O objeto que você mandou ao criar o link

Itens

Campo	Descrição
`productId`	Produto do catálogo, ou `null` para item avulso
`variantId`	Variante comprada, ou `null` quando o produto não tem variantes
`variantTitle`	Rótulo da variante, como `10ml` ou `P / Azul`
`quantity`	Unidades
`priceCents` / `totalCents`	Preço unitário e total da linha, em centavos
`kind`	`item` (comprado), `bump` (aceito no checkout) ou `gift` (brinde concedido)

Separe todas as linhas, inclusive bump e gift: tudo sai da sua loja.

Status de Pagamento

Status	Descrição
`pending`	Aguardando pagamento (Pix ou boleto gerado)
`paid`	Pago
`failed`	Recusado
`canceled`	Cancelado pelo gateway
`refunded`	Reembolsado
`partially_refunded`	Reembolsado em parte
`chargeback`	Contestado pelo comprador

Só paid libera o pedido.

Webhooks Relacionados

Evento	Quando é disparado
`order.created`	O pedido nasceu no checkout (ainda sem pagamento)
`checkout.completed`	O comprador finalizou o checkout (ainda sem pagamento)
`order.paid`	O gateway confirmou o pagamento
`order.cancelled`	O gateway cancelou o pagamento
`order.refunded`	O pagamento foi devolvido

Todos trazem o pedido inteiro em data, no formato desta página.

Webhooks

Formato do aviso, assinatura e retentativas

Pedidos

Webhooks

On this page