Create an order
curl --request POST \
--url https://api.ya.onl/v1/orders \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-API-Key: <api-key>' \
--data '
{
"sales_channel": "store",
"customer": {
"name": "<string>",
"phone_number": "+51999888777",
"email": "<string>",
"document_type": "DNI",
"document_number": "<string>"
},
"currency": "PEN",
"total_amount": 139.7,
"pending_amount": 0,
"payment_method": "Efectivo",
"items": [
{
"name": "<string>",
"quantity": 2,
"base_price": 49.9,
"variant_id": 123,
"sku": "<string>"
}
],
"contact_id": "<string>",
"delivery_fee": 123,
"payment_terms": "paid",
"address": {
"full_address": "<string>",
"country": "PERU",
"state": "Lima",
"city": "Lima",
"district": "Miraflores"
}
}
'import requests
url = "https://api.ya.onl/v1/orders"
payload = {
"sales_channel": "store",
"customer": {
"name": "<string>",
"phone_number": "+51999888777",
"email": "<string>",
"document_type": "DNI",
"document_number": "<string>"
},
"currency": "PEN",
"total_amount": 139.7,
"pending_amount": 0,
"payment_method": "Efectivo",
"items": [
{
"name": "<string>",
"quantity": 2,
"base_price": 49.9,
"variant_id": 123,
"sku": "<string>"
}
],
"contact_id": "<string>",
"delivery_fee": 123,
"payment_terms": "paid",
"address": {
"full_address": "<string>",
"country": "PERU",
"state": "Lima",
"city": "Lima",
"district": "Miraflores"
}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
sales_channel: 'store',
customer: {
name: '<string>',
phone_number: '+51999888777',
email: '<string>',
document_type: 'DNI',
document_number: '<string>'
},
currency: 'PEN',
total_amount: 139.7,
pending_amount: 0,
payment_method: 'Efectivo',
items: [
{
name: '<string>',
quantity: 2,
base_price: 49.9,
variant_id: 123,
sku: '<string>'
}
],
contact_id: '<string>',
delivery_fee: 123,
payment_terms: 'paid',
address: {
full_address: '<string>',
country: 'PERU',
state: 'Lima',
city: 'Lima',
district: 'Miraflores'
}
})
};
fetch('https://api.ya.onl/v1/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ya.onl/v1/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'sales_channel' => 'store',
'customer' => [
'name' => '<string>',
'phone_number' => '+51999888777',
'email' => '<string>',
'document_type' => 'DNI',
'document_number' => '<string>'
],
'currency' => 'PEN',
'total_amount' => 139.7,
'pending_amount' => 0,
'payment_method' => 'Efectivo',
'items' => [
[
'name' => '<string>',
'quantity' => 2,
'base_price' => 49.9,
'variant_id' => 123,
'sku' => '<string>'
]
],
'contact_id' => '<string>',
'delivery_fee' => 123,
'payment_terms' => 'paid',
'address' => [
'full_address' => '<string>',
'country' => 'PERU',
'state' => 'Lima',
'city' => 'Lima',
'district' => 'Miraflores'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ya.onl/v1/orders"
payload := strings.NewReader("{\n \"sales_channel\": \"store\",\n \"customer\": {\n \"name\": \"<string>\",\n \"phone_number\": \"+51999888777\",\n \"email\": \"<string>\",\n \"document_type\": \"DNI\",\n \"document_number\": \"<string>\"\n },\n \"currency\": \"PEN\",\n \"total_amount\": 139.7,\n \"pending_amount\": 0,\n \"payment_method\": \"Efectivo\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"base_price\": 49.9,\n \"variant_id\": 123,\n \"sku\": \"<string>\"\n }\n ],\n \"contact_id\": \"<string>\",\n \"delivery_fee\": 123,\n \"payment_terms\": \"paid\",\n \"address\": {\n \"full_address\": \"<string>\",\n \"country\": \"PERU\",\n \"state\": \"Lima\",\n \"city\": \"Lima\",\n \"district\": \"Miraflores\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.ya.onl/v1/orders")
.header("Idempotency-Key", "<idempotency-key>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"sales_channel\": \"store\",\n \"customer\": {\n \"name\": \"<string>\",\n \"phone_number\": \"+51999888777\",\n \"email\": \"<string>\",\n \"document_type\": \"DNI\",\n \"document_number\": \"<string>\"\n },\n \"currency\": \"PEN\",\n \"total_amount\": 139.7,\n \"pending_amount\": 0,\n \"payment_method\": \"Efectivo\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"base_price\": 49.9,\n \"variant_id\": 123,\n \"sku\": \"<string>\"\n }\n ],\n \"contact_id\": \"<string>\",\n \"delivery_fee\": 123,\n \"payment_terms\": \"paid\",\n \"address\": {\n \"full_address\": \"<string>\",\n \"country\": \"PERU\",\n \"state\": \"Lima\",\n \"city\": \"Lima\",\n \"district\": \"Miraflores\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ya.onl/v1/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sales_channel\": \"store\",\n \"customer\": {\n \"name\": \"<string>\",\n \"phone_number\": \"+51999888777\",\n \"email\": \"<string>\",\n \"document_type\": \"DNI\",\n \"document_number\": \"<string>\"\n },\n \"currency\": \"PEN\",\n \"total_amount\": 139.7,\n \"pending_amount\": 0,\n \"payment_method\": \"Efectivo\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"base_price\": 49.9,\n \"variant_id\": 123,\n \"sku\": \"<string>\"\n }\n ],\n \"contact_id\": \"<string>\",\n \"delivery_fee\": 123,\n \"payment_terms\": \"paid\",\n \"address\": {\n \"full_address\": \"<string>\",\n \"country\": \"PERU\",\n \"state\": \"Lima\",\n \"city\": \"Lima\",\n \"district\": \"Miraflores\"\n }\n}"
response = http.request(request)
puts response.read_body{
"address": {
"city": "Lima",
"country": "PERU",
"district": "Miraflores",
"full_address": "Av. Larco 1234, Miraflores, Lima",
"state": "Lima"
},
"currency": "PEN",
"customer": {
"document_number": "12345678",
"document_type": "DNI",
"name": "María García",
"phone_number": "+51999888777"
},
"delivery_fee": 10,
"id": 12345,
"items": [
{
"base_price": 49.9,
"name": "Polo Negro - Talla M",
"quantity": 2,
"variant_id": 500
},
{
"base_price": 59.9,
"name": "Jean Slim Fit - Talla 32",
"quantity": 1,
"variant_id": 501
}
],
"order_date": "2026-03-10T15:30:00Z",
"payment_method": "credit_card",
"payment_receipt_urls": [
"https://example.com/vouchers/voucher1.jpg"
],
"payment_terms": "paid",
"pending_amount": 0,
"status": "confirmed",
"summary_conversation": "2 Polos Negro Talla M y 1 Jean Slim Fit Talla 32. Pago con Yape. Envío a Miraflores.",
"total_amount": 139.7
}{
"type": "<string>",
"detail": "<string>"
}{
"type": "<string>",
"detail": "<string>"
}{
"type": "<string>",
"detail": "<string>",
"candidates": [
{
"contact_id": "<string>",
"name": "<string>"
}
]
}{
"type": "<string>",
"detail": "<string>"
}{
"type": "<string>",
"detail": "<string>"
}Orders
Create an order
Record a sale made outside a WhatsApp conversation (in a store, by phone, on Instagram or elsewhere) for the authenticated merchant.
POST
/
v1
/
orders
Create an order
curl --request POST \
--url https://api.ya.onl/v1/orders \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-API-Key: <api-key>' \
--data '
{
"sales_channel": "store",
"customer": {
"name": "<string>",
"phone_number": "+51999888777",
"email": "<string>",
"document_type": "DNI",
"document_number": "<string>"
},
"currency": "PEN",
"total_amount": 139.7,
"pending_amount": 0,
"payment_method": "Efectivo",
"items": [
{
"name": "<string>",
"quantity": 2,
"base_price": 49.9,
"variant_id": 123,
"sku": "<string>"
}
],
"contact_id": "<string>",
"delivery_fee": 123,
"payment_terms": "paid",
"address": {
"full_address": "<string>",
"country": "PERU",
"state": "Lima",
"city": "Lima",
"district": "Miraflores"
}
}
'import requests
url = "https://api.ya.onl/v1/orders"
payload = {
"sales_channel": "store",
"customer": {
"name": "<string>",
"phone_number": "+51999888777",
"email": "<string>",
"document_type": "DNI",
"document_number": "<string>"
},
"currency": "PEN",
"total_amount": 139.7,
"pending_amount": 0,
"payment_method": "Efectivo",
"items": [
{
"name": "<string>",
"quantity": 2,
"base_price": 49.9,
"variant_id": 123,
"sku": "<string>"
}
],
"contact_id": "<string>",
"delivery_fee": 123,
"payment_terms": "paid",
"address": {
"full_address": "<string>",
"country": "PERU",
"state": "Lima",
"city": "Lima",
"district": "Miraflores"
}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
sales_channel: 'store',
customer: {
name: '<string>',
phone_number: '+51999888777',
email: '<string>',
document_type: 'DNI',
document_number: '<string>'
},
currency: 'PEN',
total_amount: 139.7,
pending_amount: 0,
payment_method: 'Efectivo',
items: [
{
name: '<string>',
quantity: 2,
base_price: 49.9,
variant_id: 123,
sku: '<string>'
}
],
contact_id: '<string>',
delivery_fee: 123,
payment_terms: 'paid',
address: {
full_address: '<string>',
country: 'PERU',
state: 'Lima',
city: 'Lima',
district: 'Miraflores'
}
})
};
fetch('https://api.ya.onl/v1/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ya.onl/v1/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'sales_channel' => 'store',
'customer' => [
'name' => '<string>',
'phone_number' => '+51999888777',
'email' => '<string>',
'document_type' => 'DNI',
'document_number' => '<string>'
],
'currency' => 'PEN',
'total_amount' => 139.7,
'pending_amount' => 0,
'payment_method' => 'Efectivo',
'items' => [
[
'name' => '<string>',
'quantity' => 2,
'base_price' => 49.9,
'variant_id' => 123,
'sku' => '<string>'
]
],
'contact_id' => '<string>',
'delivery_fee' => 123,
'payment_terms' => 'paid',
'address' => [
'full_address' => '<string>',
'country' => 'PERU',
'state' => 'Lima',
'city' => 'Lima',
'district' => 'Miraflores'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ya.onl/v1/orders"
payload := strings.NewReader("{\n \"sales_channel\": \"store\",\n \"customer\": {\n \"name\": \"<string>\",\n \"phone_number\": \"+51999888777\",\n \"email\": \"<string>\",\n \"document_type\": \"DNI\",\n \"document_number\": \"<string>\"\n },\n \"currency\": \"PEN\",\n \"total_amount\": 139.7,\n \"pending_amount\": 0,\n \"payment_method\": \"Efectivo\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"base_price\": 49.9,\n \"variant_id\": 123,\n \"sku\": \"<string>\"\n }\n ],\n \"contact_id\": \"<string>\",\n \"delivery_fee\": 123,\n \"payment_terms\": \"paid\",\n \"address\": {\n \"full_address\": \"<string>\",\n \"country\": \"PERU\",\n \"state\": \"Lima\",\n \"city\": \"Lima\",\n \"district\": \"Miraflores\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.ya.onl/v1/orders")
.header("Idempotency-Key", "<idempotency-key>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"sales_channel\": \"store\",\n \"customer\": {\n \"name\": \"<string>\",\n \"phone_number\": \"+51999888777\",\n \"email\": \"<string>\",\n \"document_type\": \"DNI\",\n \"document_number\": \"<string>\"\n },\n \"currency\": \"PEN\",\n \"total_amount\": 139.7,\n \"pending_amount\": 0,\n \"payment_method\": \"Efectivo\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"base_price\": 49.9,\n \"variant_id\": 123,\n \"sku\": \"<string>\"\n }\n ],\n \"contact_id\": \"<string>\",\n \"delivery_fee\": 123,\n \"payment_terms\": \"paid\",\n \"address\": {\n \"full_address\": \"<string>\",\n \"country\": \"PERU\",\n \"state\": \"Lima\",\n \"city\": \"Lima\",\n \"district\": \"Miraflores\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ya.onl/v1/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sales_channel\": \"store\",\n \"customer\": {\n \"name\": \"<string>\",\n \"phone_number\": \"+51999888777\",\n \"email\": \"<string>\",\n \"document_type\": \"DNI\",\n \"document_number\": \"<string>\"\n },\n \"currency\": \"PEN\",\n \"total_amount\": 139.7,\n \"pending_amount\": 0,\n \"payment_method\": \"Efectivo\",\n \"items\": [\n {\n \"name\": \"<string>\",\n \"quantity\": 2,\n \"base_price\": 49.9,\n \"variant_id\": 123,\n \"sku\": \"<string>\"\n }\n ],\n \"contact_id\": \"<string>\",\n \"delivery_fee\": 123,\n \"payment_terms\": \"paid\",\n \"address\": {\n \"full_address\": \"<string>\",\n \"country\": \"PERU\",\n \"state\": \"Lima\",\n \"city\": \"Lima\",\n \"district\": \"Miraflores\"\n }\n}"
response = http.request(request)
puts response.read_body{
"address": {
"city": "Lima",
"country": "PERU",
"district": "Miraflores",
"full_address": "Av. Larco 1234, Miraflores, Lima",
"state": "Lima"
},
"currency": "PEN",
"customer": {
"document_number": "12345678",
"document_type": "DNI",
"name": "María García",
"phone_number": "+51999888777"
},
"delivery_fee": 10,
"id": 12345,
"items": [
{
"base_price": 49.9,
"name": "Polo Negro - Talla M",
"quantity": 2,
"variant_id": 500
},
{
"base_price": 59.9,
"name": "Jean Slim Fit - Talla 32",
"quantity": 1,
"variant_id": 501
}
],
"order_date": "2026-03-10T15:30:00Z",
"payment_method": "credit_card",
"payment_receipt_urls": [
"https://example.com/vouchers/voucher1.jpg"
],
"payment_terms": "paid",
"pending_amount": 0,
"status": "confirmed",
"summary_conversation": "2 Polos Negro Talla M y 1 Jean Slim Fit Talla 32. Pago con Yape. Envío a Miraflores.",
"total_amount": 139.7
}{
"type": "<string>",
"detail": "<string>"
}{
"type": "<string>",
"detail": "<string>"
}{
"type": "<string>",
"detail": "<string>",
"candidates": [
{
"contact_id": "<string>",
"name": "<string>"
}
]
}{
"type": "<string>",
"detail": "<string>"
}{
"type": "<string>",
"detail": "<string>"
}Autorizaciones
Merchant API key for authentication
Encabezados
Unique key for this sale. A retry carrying the same key returns the order already created instead of a second one, whatever its body, so never reuse a key for another sale.
Required string length:
1 - 120Cuerpo
application/json
A sale made outside a WhatsApp conversation, recorded against a contact.
Where the sale was made. store and phone sales may omit address; instagram and other need one.
Opciones disponibles:
store, phone, instagram, other Ejemplo:
"store"
Customer information
Show child attributes
Show child attributes
Currency code (ISO 4217)
Opciones disponibles:
MXN, PEN, COP, CLP, ARS, BRL, VES, BOB, USD, PYG, UYU, CRC, EUR, GTQ Ejemplo:
"PEN"
Total order amount including delivery fee
Ejemplo:
139.7
Amount still pending payment
Ejemplo:
0
Payment method used
Maximum string length:
100Ejemplo:
"Efectivo"
Line items in the order
Minimum array length:
1Show child attributes
Show child attributes
Contact the sale belongs to. When omitted, customer.phone_number finds or creates it.
Delivery fee charged to the customer
Payment terms for the order (pending when omitted)
Opciones disponibles:
pending, partial, paid, paid_pending_review, cash_on_delivery Ejemplo:
"paid"
Delivery address
Show child attributes
Show child attributes
Respuesta
Successful Response
Unique order identifier
Date and time when the order was placed (merchant's local timezone)
Payment method used
Ejemplo:
"credit_card"
Currency code (ISO 4217)
Opciones disponibles:
MXN, PEN, COP, CLP, ARS, BRL, VES, BOB, USD, PYG, UYU, CRC, EUR, GTQ Ejemplo:
"PEN"
Total order amount including delivery fee
Pattern:
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Ejemplo:
139.7
Customer information
Show child attributes
Show child attributes
Delivery address (null when the goods were handed over in person, as in a store or phone sale)
Show child attributes
Show child attributes
Line items in the order. Empty while the order was recorded only from a payment receipt or a merchant's mark; it gains lines later under the same id.
Show child attributes
Show child attributes
Current order status
Opciones disponibles:
pending, confirmed, preparing, ready_for_dispatch, dispatched, delivered, completed, rejected, cancelled Ejemplo:
"pending"
Payment terms for the order
Opciones disponibles:
pending, partial, paid, paid_pending_review, cash_on_delivery Ejemplo:
"paid"
Amount still pending payment (null if fully paid)
Pattern:
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Ejemplo:
0
Delivery fee charged to the customer
Pattern:
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Ejemplo:
10
URLs of payment receipt images uploaded by the customer (e.g. Yape, Plin vouchers)
AI-generated summary of the sales conversation with product details and customer preferences