Pedidos Gerencie pedidos, atualize status e acompanhe fulfillment.
A API de Pedidos permite consultar e gerenciar todos os pedidos da sua loja. Você pode listar, buscar detalhes, criar e atualizar o status dos pedidos.
Método Endpoint Descrição GET/api/sdk/ordersListar pedidos POST/api/sdk/ordersCriar pedido GET/api/sdk/orders/:idBuscar pedido PATCH/api/sdk/orders/:idAtualizar pedido
Parâmetro Tipo Descrição limitnumberMáximo de itens (1-100, padrão: 50) cursorstringCursor para paginação statusstringpending, processing, completed, cancelledpaymentStatusstringpending, paid, failed, refundedfulfillmentStatusstringunfulfilled, partial, fulfilledcustomerEmailstringFiltrar por email do cliente orderNumberstringBuscar por número do pedido searchstringBusca por número, email ou nome dateFromstringData inicial (ISO 8601) dateTostringData final (ISO 8601) sortBystringOrdenar por: createdAt, updatedAt, total, orderNumber sortOrderstringasc ou desc (padrão: desc)
cURL JavaScript Python
curl -X GET "https://api.plasmacheckout.com/api/sdk/orders?status=pending&limit=10" \ -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" const response = await fetch ( 'https://api.plasmacheckout.com/api/sdk/orders?status=pending&limit=10' , { headers: { 'X-PLASMA-Public-Key' : 'pk_live_xxxxxxxxxxxxxxxxxxxx' , 'X-PLASMA-Secret-Key' : 'sk_live_xxxxxxxxxxxxxxxxxxxx' } } ); const result = await response. json (); console. log (result.data); // array de pedidos console. log (result.pagination); // { hasMore, nextCursor, count, total } 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 = { 'status' : 'pending' , 'limit' : 10 } ) data = response.json() print (data[ 'data' ]) print (data[ 'pagination' ]) { "data" : [ { "id" : "cm5order123abc456def" , "orderNumber" : "PLS-2025-A1B2C3" , "status" : "processing" , "paymentStatus" : "paid" , "fulfillmentStatus" : "unfulfilled" , "customerEmail" : "cliente@email.com" , "customerName" : "João Silva" , "customerPhone" : "+5511999999999" , "shippingAddress" : { "street" : "Rua das Flores, 123" , "city" : "São Paulo" , "state" : "SP" , "zipCode" : "01234-567" , "country" : "BR" }, "billingAddress" : null , "items" : [ { "productId" : "cm5abc123def456ghi789" , "title" : "Camiseta Premium" , "quantity" : 2 , "price" : 7990 , "sku" : "CAM-001" } ], "subtotal" : 15980 , "shipping" : 1500 , "discount" : 0 , "tax" : 0 , "total" : 17480 , "currency" : "BRL" , "paymentMethod" : "pix" , "notes" : "" , "metadata" : null , "createdAt" : "2025-01-15T10:00:00Z" , "updatedAt" : "2025-01-15T10:30:00Z" } ], "pagination" : { "hasMore" : true , "nextCursor" : "cm5order123abc456deg" , "count" : 10 , "total" : 250 }, "filters" : { "status" : "pending" , "paymentStatus" : null , "fulfillmentStatus" : null , "customerEmail" : null , "dateFrom" : null , "dateTo" : null } } Campo Tipo Obrigatório Descrição customerobject✅ Dados do cliente customer.emailstring✅ Email do cliente (formato válido) customer.namestring❌ Nome completo customer.phonestring❌ Telefone itemsarray✅ Itens do pedido (min 1) items[].productIdstring❌ ID do produto (opcional) items[].titlestring❌ Título do item items[].quantitynumber❌ Quantidade (min 1) items[].pricenumber❌ Preço unitário em centavos items[].skustring❌ SKU do item shippingAddressobject❌ Endereço de entrega billingAddressobject❌ Endereço de cobrança (padrão: shipping) shippingnumber❌ Valor do frete em centavos discountnumber❌ Valor do desconto em centavos taxnumber❌ Valor do imposto em centavos currencystring❌ Moeda (padrão: BRL) paymentMethodstring❌ pix, credit_card, boleto, externalnotesstring❌ Observações (max 1000 chars) metadataobject❌ Dados extras
O campo items[].productId é opcional . Você pode criar pedidos com itens customizados fornecendo title e price diretamente.
cURL JavaScript
curl -X POST "https://api.plasmacheckout.com/api/sdk/orders" \ -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "customer": { "email": "cliente@email.com", "name": "João Silva", "phone": "+5511999999999" }, "items": [ { "productId": "cm5abc123def456ghi789", "title": "Camiseta Premium", "quantity": 2, "price": 7990 }, { "title": "Embalagem Presente", "quantity": 1, "price": 500 } ], "shippingAddress": { "street": "Rua das Flores, 123", "city": "São Paulo", "state": "SP", "zipCode": "01234-567", "country": "BR" }, "shipping": 1500, "tax": 0, "paymentMethod": "pix" }' const response = await fetch ( 'https://api.plasmacheckout.com/api/sdk/orders' , { method: 'POST' , headers: { 'X-PLASMA-Public-Key' : 'pk_live_xxxxxxxxxxxxxxxxxxxx' , 'X-PLASMA-Secret-Key' : 'sk_live_xxxxxxxxxxxxxxxxxxxx' , 'Content-Type' : 'application/json' }, body: JSON . stringify ({ customer: { email: 'cliente@email.com' , name: 'João Silva' , phone: '+5511999999999' }, items: [ { productId: 'cm5abc123def456ghi789' , title: 'Camiseta Premium' , quantity: 2 , price: 7990 }, { title: 'Embalagem Presente' , quantity: 1 , price: 500 } ], shippingAddress: { street: 'Rua das Flores, 123' , city: 'São Paulo' , state: 'SP' , zipCode: '01234-567' , country: 'BR' }, shipping: 1500 , paymentMethod: 'pix' }) }); const { data , message } = await response. json (); { "data" : { "id" : "cm5order123abc456def" , "orderNumber" : "PLS-2025-A1B2C3" , "status" : "pending" , "paymentStatus" : "pending" , "fulfillmentStatus" : "unfulfilled" , "subtotal" : 16480 , "shipping" : 1500 , "discount" : 0 , "tax" : 0 , "total" : 17980 , "currency" : "BRL" , "paymentMethod" : "pix" , "createdAt" : "2025-01-15T10:00:00Z" }, "message" : "Order created successfully" }
O total é calculado automaticamente: subtotal + shipping - discount + tax. O total não pode ser negativo.
Ao criar um pedido, o webhook order.created é disparado automaticamente.
Retorna o pedido com todos os itens e detalhes.
cURL JavaScript
curl -X GET "https://api.plasmacheckout.com/api/sdk/orders/cm5order123abc456def" \ -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" const response = await fetch ( 'https://api.plasmacheckout.com/api/sdk/orders/cm5order123abc456def' , { headers: { 'X-PLASMA-Public-Key' : 'pk_live_xxxxxxxxxxxxxxxxxxxx' , 'X-PLASMA-Secret-Key' : 'sk_live_xxxxxxxxxxxxxxxxxxxx' } } ); const { data } = await response. json (); PATCH /api/sdk/orders/:id Campo Tipo Descrição statusstringpending, processing, completed, cancelledpaymentStatusstringpending, paid, failed, refundedfulfillmentStatusstringunfulfilled, partial, fulfilledtrackingNumberstringCódigo de rastreio trackingUrlstringURL de rastreamento notesstringObservações internas metadataobjectMetadados extras
curl -X PATCH "https://api.plasmacheckout.com/api/sdk/orders/cm5order123abc456def" \ -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "paymentStatus": "paid" }' curl -X PATCH "https://api.plasmacheckout.com/api/sdk/orders/cm5order123abc456def" \ -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "fulfillmentStatus": "fulfilled", "trackingNumber": "BR123456789BR", "trackingUrl": "https://rastreamento.correios.com.br/BR123456789BR" }' { "data" : { "id" : "cm5order123abc456def" , "orderNumber" : "PLS-2025-A1B2C3" , "status" : "processing" , "paymentStatus" : "paid" , "fulfillmentStatus" : "fulfilled" , "trackingNumber" : "BR123456789BR" , "trackingUrl" : "https://rastreamento.correios.com.br/BR123456789BR" , "updatedAt" : "2025-01-15T11:30:00Z" }, "message" : "Order updated successfully" } Status Descrição pendingAguardando processamento processingEm processamento completedConcluído cancelledCancelado
Status Descrição pendingAguardando pagamento paidPago failedFalhou refundedReembolsado
Status Descrição unfulfilledNão enviado partialParcialmente enviado fulfilledEnviado completamente
Evento Quando é disparado order.createdPedido criado order.paidpaymentStatus atualizado para paidorder.fulfilledfulfillmentStatus atualizado para fulfilledorder.cancelledstatus atualizado para cancelledorder.refundedpaymentStatus atualizado para refunded
Os webhooks são disparados automaticamente quando você atualiza o status via API.