--- updatedAt: 2026-03-24T22:29:34.000Z agentTools: projectIndex: https://developers.digitalfemsa.io/llms.txt --- # Get a list of Orders Returns a paginated list of orders created in your account. Use pagination parameters to navigate through results, and `search` to filter by supported criteria. ## Smart Filtering The smart filter **search** allows you to search for orders based on different criteria, including "id", "customer", "email", "charge", "phone", and "amount". Additionally, if no matches are found in these fields, the filter will also search for text matches in the fields "customer name", "shipping contact email", "shipping phone", and "shipping receiver". ## Advanced Filtering In addition to having smart filters, we can filter by specific fields using an advanced filter type that helps us obtain more precise data. You can learn about our advanced filters in [Advanced Filters](https://developers.digitalfemsa.io/reference/advanced-filters). To use these filters, they are only allowed in the following fields:
Field Description
id Filters by ID
amount Filters by amount
last\_payment\_info.status Filters by last payment info status
last\_payment\_info.payment\_method Filters by payment method used.\ You can filter by: OxxoPayment
created\_at Filters by creation date
updated\_at Filters by update date
payment\_status Filters by order status
customer\_info.id Filters by customer ID
customer\_info.email Filters by customer email
customer\_info.name Filters by customer name
customer\_info.phone Filters by customer phone
# OpenAPI definition ```json { "openapi": "3.0.3", "info": { "contact": { "email": "engineering@femsa.com", "name": "Engineering Femsa", "url": "https://github.com/digitalfemsa/openapi/issues" }, "description": "Femsa sdk", "license": { "name": "MIT-LICENSE", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "title": "Femsa API", "version": "2.1.0" }, "servers": [ { "description": "Femsa main server", "url": "https://api.digitalfemsa.io" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/orders": { "get": { "description": "Returns a paginated list of orders created in your account.\nUse pagination parameters to navigate through results, and `search` to filter by supported criteria.\n", "operationId": "getOrders", "parameters": [ { "description": "Use for knowing which language to use", "examples": { "es": { "summary": "for spanish request/response", "value": "es" }, "en": { "summary": "for english request/response", "value": "en" } }, "in": "header", "name": "Accept-Language", "required": false, "schema": { "default": "es", "enum": [ "es", "en" ], "type": "string" } }, { "description": "In the case of a holding company, the company id of the child company to which will process the request.", "example": "6441b6376b60c3a638da80af", "in": "header", "name": "X-Child-Company-Id", "required": false, "schema": { "type": "string" } }, { "description": "The numbers of items to return, the maximum value is 250", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "format": "int32", "maximum": 250, "minimum": 1, "type": "integer" } }, { "description": "General order search, e.g. by mail, reference etc.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "next page", "in": "query", "name": "next", "required": false, "schema": { "type": "string" } }, { "description": "previous page", "in": "query", "name": "previous", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.app-v2.1.0+json": { "schema": { "$ref": "#/components/schemas/get_orders_response" } } }, "description": "successful operation" }, "401": { "content": { "application/vnd.app-v2.1.0+json": { "example": { "details": [ { "message": "Please include your access key in your request.", "param": null, "code": "femsa.errors.authentication.missing_key" } ], "log_id": "507f1f77bcf86cd799439011", "object": "error", "type": "authentication_error" }, "schema": { "$ref": "#/components/schemas/error" } } }, "description": "authentication error" }, "500": { "content": { "application/vnd.app-v2.1.0+json": { "example": { "details": [ { "debug_message": "There was a runtime error and Femsa engineers have been notified.", "message": "There was a runtime error and Femsa engineers have been notified.", "param": null, "code": "femsa.errors.api.system.general_failure" } ], "object": "error", "type": "api_error", "log_id": "641b6f2b3cd9a50001515098" }, "schema": { "$ref": "#/components/schemas/error" } } }, "description": "internal server error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a list of Orders", "tags": [ "Orders" ] } } }, "components": { "schemas": { "page": { "description": "page metadata", "properties": { "next_page_url": { "description": "URL of the next page.", "example": "https://api.femsa.io/resources?limit=10&next=chrg_1", "nullable": true, "type": "string" }, "previous_page_url": { "description": "Url of the previous page.", "example": "https://api.femsa.io/resources?limit=10&previous=chrg_1", "nullable": true, "type": "string" } }, "title": "page metadata", "type": "object" }, "pagination": { "description": "pagination metadata", "properties": { "has_more": { "description": "Indicates if there are more pages to be requested", "example": false, "type": "boolean" }, "object": { "description": "Object type, in this case is list", "example": "list", "type": "string" } }, "required": [ "has_more", "object" ], "title": "pagination metadata", "type": "object" }, "error": { "allOf": [ { "$ref": "#/components/schemas/details" }, { "properties": { "log_id": { "description": "log id", "example": "507f1f77bcf86cd799439011", "nullable": true, "type": "string" }, "type": { "example": "authentication_error", "type": "string" }, "object": { "example": "error", "type": "string" } }, "type": "object" } ], "description": "err model", "title": "error" }, "charge_response": { "properties": { "amount": { "example": 600000, "format": "int64", "type": "integer" }, "channel": { "$ref": "#/components/schemas/charge_response_channel" }, "created_at": { "example": 1768581166, "format": "int64", "type": "integer" }, "currency": { "example": "MXN", "type": "string" }, "customer_id": { "type": "string" }, "description": { "example": "Payment from order", "type": "string" }, "device_fingerprint": { "example": "6FR3chaU4Y1nGAW5NAGd1rcjAKa142Ba", "type": "string" }, "failure_code": { "example": "suspected_fraud", "nullable": true, "type": "string" }, "failure_message": { "example": "Este cargo ha sido declinado porque el comportamiento del comprador es sospechoso.", "nullable": true, "type": "string" }, "id": { "example": "696a682e1ef5ca00015698b7", "type": "string" }, "livemode": { "example": true, "type": "boolean" }, "object": { "type": "string" }, "order_id": { "example": "ord_2zNwzJrfNC24uQUzq", "type": "string" }, "paid_at": { "format": "int64", "nullable": true, "type": "integer" }, "payment_method": { "$ref": "#/components/schemas/charge_response_payment_method" }, "reference_id": { "description": "Reference ID of the charge", "example": "ref_2tN73UdUSNrYRPD9r", "nullable": true, "type": "string" }, "refunds": { "$ref": "#/components/schemas/charge_response_refunds" }, "status": { "example": "pending_payment", "type": "string" }, "is_refundable": { "example": false, "type": "boolean" } }, "title": "charge_response", "type": "object" }, "discount_lines_response": { "allOf": [ { "$ref": "#/components/schemas/order_discount_lines_request" }, { "properties": { "id": { "description": "The discount line id", "example": "dis_lin_2tQQ58HPgPw7StE8z", "type": "string" }, "object": { "description": "The object name", "example": "discount_line", "type": "string" }, "parent_id": { "description": "The order id", "example": "ord_2tPAmKCEJqh8RE6nY", "type": "string" } }, "required": [ "id", "object", "parent_id" ], "type": "object" } ], "title": "discount_lines_order_response", "type": "object" }, "orders_response": { "properties": { "data": { "items": { "$ref": "#/components/schemas/order_response" }, "type": "array" } }, "required": [ "data" ], "title": "orders_response", "type": "object" }, "order_response": { "description": "Order model.\nSome nested resources are returned as list previews (for example: `charges`, `line_items`), and may be `null` depending on the request/context.\nThe `checkout` field is only present when the order is linked to a checkout (`channel.checkout_request_id`).\n", "properties": { "id": { "example": "ord_2zKSF2aUY2kBRcyXJ", "type": "string" }, "object": { "enum": [ "order" ], "example": "order", "type": "string" }, "livemode": { "example": true, "type": "boolean" }, "amount": { "example": 10000, "type": "integer" }, "currency": { "example": "MXN", "maxLength": 3, "type": "string" }, "payment_status": { "description": "Current payment status of the order. It can be `null` for orders without payment information yet.", "example": "pending_payment", "nullable": true, "type": "string" }, "amount_refunded": { "example": 0, "type": "integer" }, "split_payment": { "description": "Indicates whether the order uses split payments (when available/configured).", "nullable": true, "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Metadata attached to the order.", "example": {}, "maxProperties": 100, "type": "object" }, "is_refundable": { "description": "Indicates whether the order is currently refundable.", "example": false, "type": "boolean" }, "created_at": { "example": 1767651766, "format": "int64", "type": "integer" }, "updated_at": { "example": 1767651766, "format": "int64", "type": "integer" }, "customer_info": { "$ref": "#/components/schemas/order_response_customer_info" }, "shipping_contact": { "$ref": "#/components/schemas/order_response_shipping_contact" }, "channel": { "$ref": "#/components/schemas/order_response_channel" }, "fiscal_entity": { "$ref": "#/components/schemas/order_fiscal_entity_response" }, "checkout": { "$ref": "#/components/schemas/order_response_checkout" }, "line_items": { "$ref": "#/components/schemas/order_response_products" }, "discount_lines": { "$ref": "#/components/schemas/order_response_discount_lines" }, "charges": { "$ref": "#/components/schemas/order_response_charges" }, "partial_reference": { "additionalProperties": true, "description": "Partial reference information (when applicable). Structure may vary depending on the payment flow.", "nullable": true, "type": "object" }, "payments_info": { "additionalProperties": true, "description": "Additional payment information (when available). Structure may vary.", "nullable": true, "type": "object" } }, "title": "order_response", "type": "object" }, "customer_shipping_contacts_response": { "description": "Contains the detail of the shipping addresses that the client has active or has used in Femsa", "properties": { "phone": { "example": "+525511223344", "type": "string" }, "receiver": { "example": "Marvin Fuller", "type": "string" }, "between_streets": { "example": "Ackerman Crescent", "nullable": true, "type": "string" }, "address": { "$ref": "#/components/schemas/customer_shipping_contacts_response_address" }, "parent_id": { "description": "Customer ID that owns this shipping contact.", "example": "cus_1234567890", "type": "string" }, "default": { "example": false, "type": "boolean" }, "id": { "example": "ship_cont_1234567890", "type": "string" }, "created_at": { "example": 1675715413, "format": "int64", "type": "integer" }, "metadata": { "additionalProperties": true, "description": "Metadata associated with the shipping contact", "maxProperties": 100, "type": "object" }, "object": { "example": "shipping_contact", "type": "string" }, "deleted": { "description": "Present only when the shipping contact was deleted.", "example": true, "type": "boolean" } }, "title": "customer_shipping_contacts_response", "type": "object" }, "order_discount_lines_request": { "description": "List of discounts that apply to the order.", "properties": { "amount": { "description": "The amount to be deducted from the total sum of all payments, in cents.", "example": 500, "format": "int64", "minimum": 0, "type": "integer" }, "code": { "description": "Discount code.", "example": "123", "type": "string" }, "type": { "description": "It can be 'loyalty', 'campaign', 'coupon' o 'sign'", "example": "loyalty", "type": "string" } }, "required": [ "amount", "code", "type" ], "title": "order_discount_lines_request", "type": "object" }, "product": { "properties": { "name": { "description": "The name of the item. It will be displayed in the order.", "example": "Box of Cohiba", "type": "string" }, "unit_price": { "description": "The price of the item in cents.", "example": 20000, "format": "int32", "minimum": 0, "type": "integer" }, "quantity": { "description": "The quantity of the item in the order.", "example": 1, "format": "int32", "minimum": 1, "type": "integer" }, "sku": { "description": "The stock keeping unit for the item. It is used to identify the item in the order.", "example": "XYZ12345", "type": "string" }, "brand": { "description": "The brand of the item.", "example": "Cohiba", "type": "string" }, "description": { "description": "Short description of the item", "example": "Imported From Mex.", "maxLength": 250, "type": "string" }, "tags": { "description": "List of tags for the item. It is used to identify the item in the order.", "items": { "maxLength": 249, "minLength": 2, "type": "string" }, "minItems": 1, "type": "array" }, "metadata": { "additionalProperties": true, "description": "Arbitrary key-value data for your internal use. Keys should be strings; values can be any JSON value.\n", "example": { "key": "value" }, "maxProperties": 100, "type": "object" } }, "required": [ "name", "quantity", "unit_price" ], "title": "product", "type": "object" }, "details": { "properties": { "details": { "items": { "$ref": "#/components/schemas/details_error" }, "type": "array" } }, "type": "object" }, "payment_method_cash": { "allOf": [ { "$ref": "#/components/schemas/payment_method" }, { "description": "use for cash responses", "properties": { "auth_code": { "example": "542563", "nullable": true, "type": "string" }, "cashier_id": { "example": "OINM01010", "nullable": true, "type": "string" }, "reference": { "example": "93000262276908", "type": "string" }, "barcode_url": { "example": "https://pt-common-s3-stg.s3.amazonaws.com/644ebf80f2243197aad6cd8810375b905b613dbe.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA3UN6375MP4SLLCWV%2F20230203%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230203T215750Z&X-Amz-Expires=604800&X-Amz-Security-Token=...&X-Amz-SignedHeaders=host&X-Amz-Signature=...", "type": "string" }, "expires_at": { "example": 1768802399, "format": "int64", "type": "integer" }, "service_name": { "example": "OxxoPay", "type": "string" }, "store": { "nullable": true, "type": "string", "example": null }, "store_name": { "example": "OXXO", "type": "string" } }, "title": "charge_data_payment_method_cash_response", "type": "object" } ] }, "order_customer_info_response": { "properties": { "customer_custom_reference": { "description": "Custom reference", "example": "custom_reference", "nullable": true, "type": "string" }, "name": { "example": "DevTest", "type": "string" }, "email": { "example": "test@femsa.com", "format": "email", "type": "string" }, "phone": { "example": "5522997233", "type": "string" }, "corporate": { "default": false, "type": "boolean" }, "object": { "example": "customer_info", "type": "string" } }, "title": "order_customer_info_response", "type": "object" }, "customer_info_just_customer_id_response": { "properties": { "customer_id": { "example": "cus_23874283647", "type": "string" } }, "title": "customer_info_response", "type": "object" }, "fiscal_entity_address": { "description": "Address of the fiscal entity", "properties": { "street1": { "description": "Street name and number", "example": "Nuevo Leon 254", "type": "string" }, "street2": { "description": "Street name and number", "example": "Departamento 404", "nullable": true, "type": "string" }, "postal_code": { "description": "Postal code", "example": "06100", "type": "string" }, "city": { "description": "City", "example": "Ciudad de Mexico", "type": "string" }, "state": { "description": "State", "example": "Ciudad de Mexico", "type": "string" }, "country": { "description": "this field follows the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)", "example": "MX", "type": "string" }, "external_number": { "description": "External number", "example": "123", "type": "string" } }, "required": [ "city", "country", "external_number", "postal_code", "street1" ], "title": "order_fiscal_entity_address_request", "type": "object" }, "payment_method": { "properties": { "type": { "type": "string" }, "object": { "example": "payment_source", "type": "string" } }, "required": [ "object" ], "type": "object" }, "get_orders_response": { "allOf": [ { "$ref": "#/components/schemas/orders_response" }, { "$ref": "#/components/schemas/pagination" }, { "$ref": "#/components/schemas/page" } ], "title": "get_orders_response" }, "charge_response_channel": { "properties": { "segment": { "example": "Checkout", "type": "string" }, "checkout_request_id": { "example": "f3a5bfc1-ba1c-474f-9687-46d8b75ffc90", "type": "string" }, "checkout_request_type": { "example": "Integration", "type": "string" }, "id": { "example": "channel_2zNxD65G8MBNkYksy", "type": "string" } }, "type": "object" }, "charge_response_payment_method": { "discriminator": { "mapping": { "cash_payment": "payment_method_cash" }, "propertyName": "object" }, "oneOf": [ { "$ref": "#/components/schemas/payment_method_cash" } ], "title": "charge_response_payment_method" }, "charge_response_refunds_data": { "properties": { "amount": { "example": -15000, "format": "int64", "type": "integer" }, "auth_code": { "example": "867372", "type": "string" }, "created_at": { "example": 1678226878, "format": "int64", "type": "integer" }, "expires_at": { "description": "refund expiration date", "example": 1678226878, "format": "int64", "type": "integer" }, "id": { "example": "6407b5bee1329a000175ba11", "type": "string" }, "object": { "example": "refund", "type": "string" }, "status": { "description": "refund status", "example": "pending", "type": "string" }, "payout_id": { "example": "6fca054a-8519-4c43-971e-cea35cc519bb", "type": "string" }, "reference": { "description": "payout reference for oxxo stores", "example": "12002000778626", "type": "string" } }, "required": [ "amount", "created_at", "id", "object" ], "title": "charge_response_refunds_data", "type": "object" }, "charge_response_refunds": { "allOf": [ { "$ref": "#/components/schemas/pagination" }, { "$ref": "#/components/schemas/page" }, { "properties": { "data": { "description": "refunds", "items": { "$ref": "#/components/schemas/charge_response_refunds_data" }, "type": "array" } }, "type": "object" } ], "nullable": true, "title": "charge_response_refunds", "type": "object" }, "order_response_customer_info": { "allOf": [ { "properties": { "object": { "example": "customer_info", "type": "string" } }, "type": "object" }, { "$ref": "#/components/schemas/order_customer_info_response" }, { "$ref": "#/components/schemas/customer_info_just_customer_id_response" } ], "description": "Customer information associated with the order." }, "order_response_shipping_contact": { "allOf": [ { "properties": { "created_at": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "object": { "type": "string" } }, "type": "object" }, { "$ref": "#/components/schemas/customer_shipping_contacts_response" } ], "description": "Shipping contact associated with the order. It may be `null` when not provided/required.", "nullable": true }, "order_response_channel": { "description": "Channel information for the order (for example Checkout-related metadata). It may be `null`.", "nullable": true, "properties": { "segment": { "example": "Checkout", "type": "string" }, "checkout_request_id": { "example": "6fca054a-8519-4c43-971e-cea35cc519bb", "type": "string" }, "checkout_request_type": { "example": "HostedPayment", "type": "string" }, "id": { "example": "channel_2tNDzhA4Akmzj11AU", "type": "string" } }, "type": "object" }, "order_fiscal_entity_address_response": { "allOf": [ { "$ref": "#/components/schemas/fiscal_entity_address" }, { "properties": { "object": { "example": "fiscal_entity_address", "type": "string" } }, "type": "object" } ], "description": "Address of the fiscal entity", "title": "order_fiscal_entity_address_response" }, "order_fiscal_entity_response": { "description": "Fiscal entity information associated with the order. This field can be `null`.", "nullable": true, "properties": { "address": { "$ref": "#/components/schemas/order_fiscal_entity_address_response" }, "email": { "description": "Email of the fiscal entity", "example": "test@gmail.com", "nullable": true, "type": "string" }, "metadata": { "additionalProperties": true, "description": "Metadata associated with the fiscal entity", "maxProperties": 100, "type": "object" }, "name": { "description": "Name of the fiscal entity", "example": "Femsa Inc", "nullable": true, "type": "string" }, "tax_id": { "description": "Tax ID of the fiscal entity", "example": "324234234", "nullable": true, "type": "string" }, "id": { "description": "ID of the fiscal entity", "example": "fis_ent_2tN85VYaSMyDvjB3M", "type": "string" }, "created_at": { "description": "The time at which the object was created in seconds since the Unix epoch", "example": 1676328434, "format": "int64", "type": "integer" }, "object": { "example": "fiscal_entity", "type": "string" }, "phone": { "description": "Phone of the fiscal entity", "example": "+525511223344", "nullable": true, "type": "string" } }, "required": [ "address", "created_at", "id", "object" ], "title": "order_fiscal_entity_response", "type": "object" }, "order_response_checkout": { "description": "Checkout resource linked to the order. Present only when the order is linked to a checkout (`channel.checkout_request_id`).", "properties": { "allowed_payment_methods": { "items": { "type": "string" }, "type": "array" }, "can_not_expire": { "example": false, "type": "boolean" }, "emails_sent": { "example": 0, "type": "integer" }, "expires_at": { "example": 1676613599, "format": "int64", "type": "integer" }, "failure_url": { "example": "http://187.216.228.66:2222/SysVentasPagos/Acceso.aspx", "type": "string" }, "id": { "example": "6fca054a-8519-4c43-971e-cea35cc519bb", "type": "string" }, "is_redirect_on_failure": { "example": false, "type": "boolean" }, "livemode": { "example": false, "type": "boolean" }, "metadata": { "additionalProperties": true, "maxProperties": 100, "type": "object" }, "name": { "example": "ord-2tNDzhA4Akmzj11AS", "type": "string" }, "needs_shipping_contact": { "example": false, "type": "boolean" }, "object": { "example": "checkout", "type": "string" }, "on_demand_enabled": { "example": true, "nullable": true, "type": "boolean" }, "recurrent": { "example": false, "type": "boolean" }, "slug": { "example": "6fca054a85194c43971ecea35cc519bb", "type": "string" }, "sms_sent": { "example": 0, "type": "integer" }, "success_url": { "example": "http://187.216.228.66:2222/SysVentasPagos/Acceso.aspx", "type": "string" }, "starts_at": { "example": 1676354400, "type": "integer" }, "status": { "example": "Issued", "type": "string" }, "type": { "example": "HostedPayment", "type": "string" }, "url": { "example": "https://pay.stg.femsa.io/checkout/6fca054a85194c43971ecea35cc519bb", "type": "string" } }, "type": "object" }, "product_data_response": { "allOf": [ { "$ref": "#/components/schemas/product" }, { "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "parent_id": { "type": "string" } }, "type": "object" } ], "title": "product_data_response" }, "order_response_products": { "allOf": [ { "$ref": "#/components/schemas/pagination" }, { "$ref": "#/components/schemas/page" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/product_data_response" }, "type": "array" } }, "type": "object" } ], "title": "order_response_products" }, "order_response_discount_lines": { "allOf": [ { "$ref": "#/components/schemas/pagination" }, { "properties": { "data": { "items": { "allOf": [ { "$ref": "#/components/schemas/discount_lines_response" } ], "title": "discount_lines_data_response" }, "type": "array" } }, "type": "object" } ] }, "order_response_charges": { "allOf": [ { "$ref": "#/components/schemas/pagination" }, { "properties": { "data": { "items": { "allOf": [ { "$ref": "#/components/schemas/charge_response" } ], "title": "charges_data_response" }, "type": "array" } }, "type": "object" } ], "description": "List preview of charges created for the order.\nCharges are only created when included in the request or created later through payment flows.\nThis field can be `null` depending on the response context.\n" }, "customer_shipping_contacts_response_address": { "properties": { "object": { "example": "shipping_address", "type": "string" }, "street1": { "example": "Nuevo Leon 254", "type": "string" }, "street2": { "example": "Departamento 404", "type": "string" }, "postal_code": { "example": "06100", "type": "string" }, "city": { "example": "Ciudad de Mexico", "type": "string" }, "state": { "example": "Ciudad de Mexico", "type": "string" }, "country": { "example": "MX", "type": "string" }, "residential": { "example": true, "nullable": true, "type": "boolean" } }, "type": "object" }, "details_error": { "properties": { "code": { "example": "femsa.errors.authentication.missing_key", "type": "string" }, "param": { "nullable": true, "type": "string" }, "message": { "example": "Acceso no autorizado.", "type": "string" }, "debug_message": { "example": "Please include your access key in your request.", "type": "string" } }, "title": "details_error", "type": "object" } }, "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ```