> ## Documentation Index > Fetch the complete documentation index at: https://docs.ya.works/llms.txt > Use this file to discover all available pages before exploring further. # Create an order > Record a sale made outside a WhatsApp conversation (in a store, by phone, on Instagram or elsewhere) for the authenticated merchant. ## OpenAPI ````yaml /openapi.json post /v1/orders openapi: 3.1.0 info: title: YV Business API description: >- Public API for YaVendio merchants to access orders, product catalog, conversations, contacts and company profile, and to send WhatsApp template messages. ## Authentication All endpoints require a valid API key sent via the `X-API-Key` header. API keys are created and managed from the [YaVendio Dashboard](https://ya.onl) under **Settings → API Keys**. Use the **Authorize** button above to set your key for all requests. Every endpoint declares the scope it requires (e.g. `orders:read`, `orders:write`, `products:write`, `conversations:read`, `contacts:read`, `company:read`, `outbound:send`, `outbound:read`), listed on its reference page. A key created from the dashboard has access to every endpoint except order creation: `orders:write` is held only by a key it was granted to explicitly when the key was created. A key that lacks the scope an endpoint requires gets `403 Forbidden`. ## Rate Limiting Requests are rate-limited per merchant. Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Check these headers to know your current limit and remaining quota. When the limit is exceeded, the API responds with `429 Too Many Requests` and adds a `Retry-After` header. ## Pagination List endpoints support pagination via `page` and `limit` query parameters. Responses include a `pagination` object with `total_pages`, `total_items`, and `has_more` fields. Maximum `limit` is 100. version: 1.15.0 servers: - url: https://api.ya.onl security: [] tags: - name: Orders description: Retrieve merchant orders and record direct sales. - name: Products description: CRUD operations on merchant products. - name: Product Variants description: Manage variants of a product. - name: Product Options description: Manage product options. - name: Product Option Values description: Manage individual option values. - name: Product Media description: Manage media files attached to product variants. - name: Categories description: CRUD operations on merchant categories (tags). - name: Product Categories description: Assign and remove categories from products. - name: Catalogs description: Retrieve merchant catalogs. - name: Webhooks description: Manage webhook subscriptions for real-time order events. - name: Conversations description: Read WhatsApp conversations and their messages. - name: Contacts description: Retrieve campaign contacts. - name: Company description: Retrieve the merchant's company profile. - name: Templates description: >- List the WhatsApp templates approved for the merchant, with the variables each one expects. - name: Template Messages description: >- Send approved WhatsApp templates to customers and follow their delivery status. paths: /v1/orders: post: tags: - Orders summary: Create an order description: >- Record a sale made outside a WhatsApp conversation (in a store, by phone, on Instagram or elsewhere) for the authenticated merchant. operationId: create_order_v1_orders_post parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 120 description: >- 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. title: Idempotency-Key description: >- 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderCreateRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OrderResponse' headers: X-RateLimit-Limit: description: Maximum number of requests allowed in the current window schema: type: integer example: 100 X-RateLimit-Remaining: description: Number of requests remaining in the current window schema: type: integer example: 87 X-RateLimit-Reset: description: Unix timestamp when the rate limit window resets schema: type: integer example: 1710288000 '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '403': description: API key lacks the `orders:write` scope content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '409': description: >- The customer's phone matches several contacts (`contact_ambiguous`, with `candidates`), or another conflict the order cannot be recorded through content: application/json: schema: $ref: '#/components/schemas/OrderConflictResponse' '422': description: >- Invalid request or order: a missing `Idempotency-Key`, a malformed body, or an order the store refuses (`invalid_order`) '429': description: Rate limit exceeded headers: X-RateLimit-Limit: description: Maximum number of requests allowed in the current window schema: type: integer example: 100 X-RateLimit-Remaining: description: Number of requests remaining in the current window schema: type: integer example: 87 X-RateLimit-Reset: description: Unix timestamp when the rate limit window resets schema: type: integer example: 1710288000 Retry-After: description: Seconds to wait before making another request schema: type: integer example: 30 content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' '502': description: >- An internal service failed or timed out; retry with the same `Idempotency-Key` content: application/json: schema: $ref: '#/components/schemas/APIErrorResponse' security: - APIKeyHeader: [] components: schemas: OrderCreateRequest: properties: sales_channel: type: string enum: - store - phone - instagram - other title: Sales Channel description: >- Where the sale was made. `store` and `phone` sales may omit `address`; `instagram` and `other` need one. examples: - store contact_id: anyOf: - type: string - type: 'null' title: Contact Id description: >- Contact the sale belongs to. When omitted, `customer.phone_number` finds or creates it. customer: $ref: '#/components/schemas/OrderCreateCustomer' description: Customer information currency: $ref: '#/components/schemas/SupportedCurrency' description: Currency code (ISO 4217) examples: - PEN total_amount: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Total Amount description: Total order amount including delivery fee examples: - 139.7 pending_amount: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Pending Amount description: Amount still pending payment examples: - 0 delivery_fee: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Delivery Fee description: Delivery fee charged to the customer payment_terms: anyOf: - $ref: '#/components/schemas/PaymentTerms' - type: 'null' description: Payment terms for the order (`pending` when omitted) examples: - paid payment_method: type: string maxLength: 100 title: Payment Method description: Payment method used examples: - Efectivo items: items: $ref: '#/components/schemas/OrderCreateItem' type: array minItems: 1 title: Items description: Line items in the order address: anyOf: - $ref: '#/components/schemas/OrderAddress' - type: 'null' description: Delivery address type: object required: - sales_channel - customer - currency - total_amount - pending_amount - payment_method - items title: OrderCreateRequest description: A sale made outside a WhatsApp conversation, recorded against a contact. OrderResponse: properties: id: type: integer title: Id description: Unique order identifier order_date: type: string format: date-time title: Order Date description: Date and time when the order was placed (merchant's local timezone) status: anyOf: - $ref: '#/components/schemas/OrderStatus' - type: 'null' description: Current order status examples: - pending payment_terms: anyOf: - $ref: '#/components/schemas/PaymentTerms' - type: 'null' description: Payment terms for the order examples: - paid payment_method: type: string title: Payment Method description: Payment method used examples: - credit_card currency: $ref: '#/components/schemas/SupportedCurrency' description: Currency code (ISO 4217) examples: - PEN total_amount: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Total Amount description: Total order amount including delivery fee examples: - 139.7 pending_amount: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Pending Amount description: Amount still pending payment (null if fully paid) examples: - 0 delivery_fee: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Delivery Fee description: Delivery fee charged to the customer examples: - 10 customer: $ref: '#/components/schemas/OrderCustomer' description: Customer information address: anyOf: - $ref: '#/components/schemas/OrderAddress' - type: 'null' description: >- Delivery address (null when the goods were handed over in person, as in a store or phone sale) items: items: $ref: '#/components/schemas/OrderItem' type: array title: Items description: >- 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. payment_receipt_urls: items: type: string type: array title: Payment Receipt Urls description: >- URLs of payment receipt images uploaded by the customer (e.g. Yape, Plin vouchers) summary_conversation: anyOf: - type: string - type: 'null' title: Summary Conversation description: >- AI-generated summary of the sales conversation with product details and customer preferences type: object required: - id - order_date - payment_method - currency - total_amount - customer - address - items title: OrderResponse examples: - 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 APIErrorResponse: properties: type: type: string title: Type description: Error type identifier, e.g. 'UnauthorizedError' detail: type: string title: Detail description: Human-readable error message type: object required: - type - detail title: APIErrorResponse OrderConflictResponse: properties: type: type: string title: Type description: Error type identifier, e.g. 'UnauthorizedError' detail: type: string title: Detail description: Human-readable error message candidates: anyOf: - items: $ref: '#/components/schemas/OrderContactCandidate' type: array - type: 'null' title: Candidates description: >- Contacts the customer's phone matched, present when `type` is `contact_ambiguous`. Retry with one of them as `contact_id`. type: object required: - type - detail title: OrderConflictResponse OrderCreateCustomer: properties: name: type: string minLength: 1 title: Name description: Customer full name phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: >- Customer phone in international format: `+`, country code and number. Required when `contact_id` is not sent; it finds the customer's contact or creates one. examples: - '+51999888777' email: anyOf: - type: string - type: 'null' title: Email description: Customer email document_type: anyOf: - type: string - type: 'null' title: Document Type description: Customer ID document type examples: - DNI - RUC document_number: anyOf: - type: string - type: 'null' title: Document Number description: Customer ID document number type: object required: - name title: OrderCreateCustomer SupportedCurrency: type: string enum: - MXN - PEN - COP - CLP - ARS - BRL - VES - BOB - USD - PYG - UYU - CRC - EUR - GTQ title: SupportedCurrency description: List of supported currencies. PaymentTerms: type: string enum: - pending - partial - paid - paid_pending_review - cash_on_delivery title: PaymentTerms description: Payment terms. OrderCreateItem: properties: variant_id: anyOf: - type: integer - type: 'null' title: Variant Id description: Catalog variant identifier sku: anyOf: - type: string - type: 'null' title: Sku description: Product variant SKU code name: type: string title: Name description: Product variant name quantity: type: integer exclusiveMinimum: 0 title: Quantity description: Number of units sold examples: - 2 base_price: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Base Price description: Unit price examples: - 49.9 type: object required: - name - quantity - base_price title: OrderCreateItem OrderAddress: properties: full_address: type: string title: Full Address description: Full delivery address as a single string country: $ref: '#/components/schemas/SupportedCountry' description: Supported country name examples: - PERU state: anyOf: - type: string - type: 'null' title: State description: State or region examples: - Lima city: anyOf: - type: string - type: 'null' title: City description: City name examples: - Lima district: anyOf: - type: string - type: 'null' title: District description: District or neighborhood examples: - Miraflores type: object required: - full_address - country title: OrderAddress OrderStatus: type: string enum: - pending - confirmed - preparing - ready_for_dispatch - dispatched - delivered - completed - rejected - cancelled title: OrderStatus description: Order status. OrderCustomer: properties: name: type: string title: Name description: Customer full name phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: Customer phone number document_type: anyOf: - type: string - type: 'null' title: Document Type description: Customer ID document type examples: - DNI - RUC document_number: anyOf: - type: string - type: 'null' title: Document Number description: Customer ID document number type: object required: - name title: OrderCustomer OrderItem: properties: variant_id: anyOf: - type: integer - type: 'null' title: Variant Id description: Internal variant identifier (null for historical orders) sku: anyOf: - type: string - type: 'null' title: Sku description: Product variant SKU code (null for historical orders) name: type: string title: Name description: Product variant name quantity: type: integer title: Quantity description: Number of units ordered examples: - 2 base_price: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Base Price description: Original unit price before discounts examples: - 49.9 type: object required: - name - quantity - base_price title: OrderItem OrderContactCandidate: properties: contact_id: type: string title: Contact Id description: Contact identifier to retry with name: anyOf: - type: string - type: 'null' title: Name description: Contact name type: object required: - contact_id title: OrderContactCandidate SupportedCountry: type: string enum: - MEXICO - PERU - COLOMBIA - CHILE - ARGENTINA - BRAZIL - VENEZUELA - BOLIVIA - ECUADOR - PARAGUAY - URUGUAY - PANAMA - COSTA_RICA - GUATEMALA - GLOBAL title: SupportedCountry description: List of supported countries. securitySchemes: APIKeyHeader: type: apiKey description: Merchant API key for authentication in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.