Create order

Creates a new order (products + amounts + customer data).

Minimum required fields:

currency
line_items
customer_info

About customer_info:

You can reference an existing customer using customer_info.customer_id, or
You can provide customer details at minimum customer_info.name and customer_info.email to create the order with customer context.

How to create the order:

Create an order only (no payment): send only the order data.
Create an order and create the first payment charge: include charges.
Create an order with a checkout configuration (for a hosted payment flow): include checkout.

Important rules:

You cannot send charges and checkout in the same request (they are mutually exclusive).
If you send shipping_contact_id and/or fiscal_entity_id, you must also send customer_info.customer_id so the API can validate those IDs against that customer.

Accept-Language'es' | 'en'

Use for knowing which language to use

X-Child-Company-Idstring

In the case of a holding company, the company id of the child company to which will process the request.

Request body

currencystring required

Currency with which the payment will be made.

needs_shipping_contactboolean

Allows you to fill out the shipping information at checkout

processing_modestring

Indicates the processing mode for the order, either ecommerce, recurrent or validation.

metadataobject

Arbitrary key-value data that you can attach to the order for your internal use (e.g. customer_segment, sales_channel, internal_order_id). It is not used for payment processing or fraud decisions. Keys should be strings; values can be any JSON value.

Example request

{
  "currency": "MXN",
  "customer_info": {
    "customer_id": "cus_23874283647",
    "name": "DevTest",
    "email": "test@femsa.com",
    "phone": "5522997233"
  },
  "line_items": [
    {
      "name": "Box of Cohiba",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "XYZ12345",
      "brand": "Cohiba",
      "description": "Imported From Mex.",
      "metadata": {
        "key": "value"
      }
    }
  ],
  "charges": [
    {
      "amount": 40000,
      "payment_method": {
        "expires_at": 1789928542,
        "type": "cash",
        "payment_source_id": "src_2tLkkyfMPh6v7pFry"
      },
      "reference_id": "ref_2tN73UdUSNrYRPD9r"
    }
  ],
  "checkout": {
    "allowed_payment_methods": [
      "cash"
    ],
    "on_demand_enabled": true,
    "type": "Integration"
  },
  "discount_lines": [
    {
      "amount": 500,
      "code": "123",
      "type": "loyalty"
    }
  ],
  "tax_lines": [
    {
      "amount": 100,
      "description": "testing",
      "metadata": {
        "key": "value"
      }
    }
  ],
  "shipping_contact": {
    "phone": "+525511223344",
    "receiver": "Marvin Fuller",
    "between_streets": "Ackerman Crescent",
    "address": {
      "street1": "Nuevo Leon 254",
      "street2": "Departamento 404",
      "postal_code": "06100",
      "city": "Ciudad de Mexico",
      "state": "Ciudad de Mexico",
      "country": "MX",
      "residential": true
    }
  },
  "shipping_lines": [
    {
      "amount": 100,
      "carrier": "FEDEX",
      "tracking_number": "TRACK123",
      "method": "Same day",
      "description": "Shipping line",
      "metadata": {
        "key": "value"
      }
    }
  ],
  "fiscal_entity": {
    "address": {
      "street1": "Nuevo Leon 254",
      "street2": "Departamento 404",
      "postal_code": "06100",
      "city": "Ciudad de Mexico",
      "state": "Ciudad de Mexico",
      "country": "MX",
      "external_number": "123"
    }
  },
  "processing_mode": "ecommerce"
}

Response

successful operation

v1

Create order

Headers

Request body

Example request

Response