Billings Management

⚠️
IMPORTANT
To follow the steps below, it is essential to have the corresponding Authorization Token. For more information, please refer to the following documentation page: Authorization Token

Create Order Invoice

💻
Visit our API Reference to test this endpoint.

❗️
For Verifacti invoice creation go to Verifactu Integration and Create Order Invoice (Verifactu).

Endpoint

POST https://pay.ecart.com/api/billings
POST https://sandbox.ecartpay.com/api/billings

Headers

Authorization: token

Query Parameters

country: ISO country code (e.g., MX for Mexico).
- This query param acts as the inital prefix of the sequence base for the invoice number.

Request Body

currency: The currency for the billing (e.g., MXN, USD).
order_id: The unique identifier of the order associated with this billing.
items: An array of items with the following details for each:
- name: Name of the item or service.
- quantity: Quantity of the item.
- price: Price per unit of the item.
- discount: Discount amount applied to the item.
- total: Total amount for the item (price × quantity - discount).
- tax: Tax amount for the item.
- fiscal_code: SAT fiscal product/service code (Clave de Producto/Servicio).
- unit_code: SAT unit of measure code (Clave de Unidad).
- is_service: Boolean indicating if the item is a service (true) or product (false).
- taxes: Tax amount or tax details.
billing_information: An object containing all billing details:
- currency: Currency for the billing transaction. (Can be null if already included above or not needed.)
- serie: SAT serie id associated with the type of CFDI/invoice created.
- payment_method: SAT payment method code (e.g., 04 for credit card).
- payment_method_type: Payment type code - PUE (Pago en una sola exhibición) or PPD (Pago en parcialidades o diferido).
- billing_at: Date when the billing is created (ISO 8601 format).
- state: Full state name (can be empty if not required).
- state_name: Full state name duplicate (can be empty if not required).
- rfc: Mexican Federal Taxpayer Registry number.
- razons: Legal business name or full legal name (Razón Social).
- regimen: Tax regime code assigned by SAT.
- invoice_use: SAT use of CFDI
- email: Primary email address for billing communications.
- first_name: First name of the billing contact.
- last_name: Last name of the billing contact.
- phone: Contact phone number.
- country_code: ISO 3166-1 alpha-2 country code.
- postal_code: Postal/ZIP code for the billing address.
- address1: Primary street address.
- address2: Secondary address line (apartment, suite, building number).
- district: Neighborhood or district name.
- state_code: Two-letter state code.
- city: City or municipality name.
- id: Billing information ID if updating existing billing data.
billing_config: An object containing specific configuration options for the invoice.
- indicator: Serves as a functional document identifier used to categorize different types of invoices or transactions within the serialization logic.
  - Purpose: It acts as a prefix (following the country code, which is obtained from the country query param or the locales field in the request body, if included) to separate invoice sequences by department or transaction type (e.g., "COM" for Commercial, "REC" for Receipts).
  Example: A request to create an order invoice with country=MX as query param with an "indicator": "COM" in the request body results in a sequence base of MXCOM-# (X stands for the corresponding numeration counter).
- serie_date: The serie_date is a temporal serialization toggle that determines whether the invoice number should be time-stamped at the month/year level. Can be true or false.
  - Purpose: When set to true, it triggers the inclusion of an additional date-based prefix in the invoice number to facilitate monthly accounting and prevent sequence collisions across different periods.
  - Behavior: It appends a 4-digit suffix in YYMM format (e.g., "2512" for December 2025) to the invoice prefix.
    
    Example: A request made in December 2025 to create an order invoice with country=MX as query param, with an "indicator": "COM", and "serie_date": true in the request body results in a sequence base of MXCOM2512-# (# stands for the corresponding numeration counter).

Examples

Request

curl --location 'http://localhost:9000/api/billings?country=MX' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI........' \
--header 'Content-Type: application/json' \
--data-raw '{
    "currency": "MXN",
    "items": [
        {
            "fiscal_code": "78102200",
            "name": "Camisa Azul",
            "quantity": "1",
            "price": 250,
            "discount": 0,
            "total": 250,
            "unit_code": "E48"
        }
    ],
    "billing_information": {
        "currency": null,
        "serie": "5488142",
        "invoice_use": "S01",
        "payment_method": "04",
        "payment_method_type": "PUE",
        "state": "",
        "state_name": "",
        "rfc": "XAXX010101000",
        "razons": "PUBLICO EN GENERAL",
        "regimen": "612",
        "email": "[email protected]",
        "first_name": "Publico",
        "last_name": "General",
        "phone": "12345678",
        "country_code": "MX",
        "postal_code": "21039",
        "address1": "Calle Prueba",
        "address2": "200",
        "district": "Distrito Prueba",
        "state_code": "NL",
        "city": "Ciudad Prueba",
        "id": "68e808e65cfe510f53d1cf0e"
    },
    "billing_config": {
        "indicator": "COM",
        "serie_date": true
    }
}'

curl --location 'http://sandbox.ecartpay.com/api/billings?country=MX' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIj.......' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_id": "6945acadace40e5592eb2270",
    "items": [
        {
            "name": "Instalación de Licencia Software (Estándar)",
            "price": 100.00,
            "quantity": 2,
            "discount": 0,
            "fiscal_code": "78102200",
            "unit_code": "E48"
        },
        {
            "name": "Instalación de Licencia Software (Pro)",
            "price": 105.00,
            "quantity": 1,
            "discount": 0,
            "fiscal_code": "78102200",
            "unit_code": "E48"
        }
    ],
    "billing_information": {
        "currency": "MXN",
        "serie": "5488142",
        "rfc": "XAXX010101000",
        "razons": "PUBLICO EN GENERAL",
        "postal_code": "21039",
        "regimen": "612",
        "invoice_use": "S01",
        "payment_method": "04",
        "payment_method_type": "PUE",
        "email": "[email protected]"
    },
    "billing_config": {
        "indicator": "COM",
        "serie_date": true
    }
}'

Response

{
    "order_id": "6945ad56ace40e5592eb22af",
    "account_id": "68a4c3150b28a9584305a2a6",
    "provider_id": "6227845d6f5e10a27680b38d",
    "provider_invoice_id": "6945adb44f064",
    "provider_invoice_uuid": "5d0380a5-8518-43ea-a433-216445e1fada",
    "number": "MXCOM2512-11",
    "status": "created",
    "name": "Publico General",
    "notes": [],
    "relations": [],
    "invoice": {
        "currency": null,
        "serie": "5488142",
        "invoice_use": "S01",
        "payment_method": "04",
        "payment_method_type": "PUE",
        "rfc": "XAXX010101000",
        "razons": "PUBLICO EN GENERAL",
        "regimen": "612",
        "email": "[email protected]",
        "first_name": "Publico",
        "last_name": "General",
        "phone": "12345678",
        "country_code": "MX",
        "postal_code": "21039",
        "address1": "Calle Prueba",
        "address2": "200",
        "district": "Distrito Prueba",
        "state_code": "NL",
        "city": "Ciudad Prueba",
        "id": "68e808e65cfe510f53d1cf0e",
        "indicator": "COM",
        "serie_date": true
    },
    "items": [
        {
            "name": "Camisa Azul",
            "quantity": 1,
            "price": 250,
            "discount": 0,
            "total": 250,
            "tax": 0,
            "fiscal_code": "78102200",
            "unit_code": "E48",
            "is_service": false,
            "taxes": []
        }
    ],
    "totals": {
        "subtotal": 250,
        "total": 250,
        "tax": 0,
        "financial_cost": 0,
        "discount": 0,
        "shipping": 0
    },
    "billing_at": "2025-12-19T19:53:58.205Z",
    "id": "6945ad5cace40e5592eb22b8",
    "created_at": "2025-12-19T19:54:04.691Z",
    "updated_at": "2025-12-19T19:54:04.691Z",
    "link": "http://localhost:9000/billing?order_id=6945ad56ace40e5592eb22af"
}

{
    "order_id": "6945acadace40e5592eb2270",
    "account_id": "68a4c3150b28a9584305a2a6",
    "provider_id": "6227845d6f5e10a27680b38d",
    "provider_invoice_id": "6945ad1bbffd7",
    "provider_invoice_uuid": "083b952c-b6aa-4187-a927-d4c5940b3c4e",
    "number": "MXCOM2512-10",
    "status": "created",
    "name": "Publico General",
    "notes": [],
    "relations": [],
    "invoice": {
        "currency": "MXN",
        "serie": "5488142",
        "rfc": "XAXX010101000",
        "razons": "PUBLICO EN GENERAL",
        "postal_code": "21039",
        "regimen": "612",
        "invoice_use": "S01",
        "payment_method": "04",
        "payment_method_type": "PUE",
        "email": "[email protected]",
        "indicator": "COM",
        "serie_date": true
    },
    "items": [
        {
            "name": "Instalación de Licencia Software (Estándar)",
            "price": 100,
            "quantity": 2,
            "discount": 0,
            "fiscal_code": "78102200",
            "unit_code": "E48",
            "is_service": false
        },
        {
            "name": "Instalación de Licencia Software (Pro)",
            "price": 105,
            "quantity": 1,
            "discount": 0,
            "fiscal_code": "78102200",
            "unit_code": "E48",
            "is_service": false
        }
    ],
    "totals": {
        "subtotal": 305,
        "total": 305,
        "tax": 0,
        "financial_cost": 0,
        "discount": 0,
        "shipping": 0
    },
    "billing_at": "2025-12-19T19:51:25.678Z",
    "id": "6945acc4ace40e5592eb228a",
    "created_at": "2025-12-19T19:51:32.152Z",
    "updated_at": "2025-12-19T19:51:32.152Z",
    "link": "http://sandbox.ecartpay.com/billing?order_id=6945acadace40e5592eb2270"
}

Create Client Billing Information

This endpoint is for gathering customer billing information which can later be used to generate invoices.

💻
Visit our API Reference to test this endpoint.

Endpoint

POST https://sandbox.ecartpay.com/api/billings/clients
POST https://pay.ecart.com/api/billings/clients

Headers

Authorization: token

Query Parameters

**provider_id**: Provider identifier. Check the Get Billing Providers endpoint to consult the provider's id.

Request Body

user_id: The unique identifier for the user in the system.
billing_information: An object containing all billing details:
- country_code: ISO 3166-1 alpha-2 country code (e.g., MX, US).
- rfc: Mexican Federal Taxpayer Registry number (RFC).
- razons: Legal business name or company name (Razón Social).
- regimen: Tax regime code assigned by SAT (e.g., 612 for natural persons with business activities).
- email: Primary email address for billing communications.
- first_name: First name of the billing contact.
- last_name: Last name of the billing contact.
- phone: Contact phone number.
- postal_code: Postal/ZIP code for the billing address.
- city: City or municipality name.
- state: Full state name.
- state_name: Full state name (duplicate for validation).
- state_code: Two-letter state code.
- address1: Primary street address.
- address2 (optional): Secondary address line (apartment, suite, building number).
- district (optional): Neighborhood or district name.

Examples

Request

curl --location 'https://pay.ecart.com/api/billings/clients?provider_id=6227845d6f5e10a27680b38d' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYxODlkNGM0ZTFmZDY1NTEyZTljNTI2NCIsImFjY291bnRfaWQiOiJ1bmRlZmluZWQiLCJ1c2VyIjoiNTkwNDc0IiwiaWF0IjoxNzU5NTA3ODY0LCJleHAiOjE3NTk1MDkwNjQsImF1ZCI6Imh0dHBzOi8vcGF5LmVjYXJ0LmNvbSJ9.E3hkSBgZ8rKjQK2WAbf3cXdEfLnEQMK6HTZL6XAVkoK8fbYfLJ7eTxgnca9biBJkaqDakmDRi8NAHdWokirYJw' \
--header 'Content-Type: application/json' \
--data '{
    "user_id": "590475",
    "billing_information": {
        "country_code": "MX",
        "rfc": "MOGH950714LL7",
        "razons": "prime95 LLC",
        "regimen": "612",
        "email": "[email protected]",
        "first_name": "Hugo",
        "last_name": "Boss",
        "phone": "8116121234",
        "postal_code": "97745",
        "city": "Cunas",
        "state": "Yucatán",
        "state_name": "Yucatán",
        "state_code": "YU",
        "address1": "Calle 77",
        "address2": "700",
        "district": "Real de Cunas"
    }
}'

Response

{
    "RazonSocial": "PRIME95 LLC",
    "RFC": "MOGH950714LL7",
    "Regimen": "Personas Físicas con Actividades Empresariales y Profesionales",
    "RegimenId": "612",
    "Calle": "Calle 77",
    "Numero": "700",
    "Interior": null,
    "Colonia": "Real de Cunas",
    "CodigoPostal": "97745",
    "Ciudad": "Cunas",
    "Delegacion": "Cunas",
    "Estado": "YU",
    "Pais": "MX",
    "NumRegIdTrib": null,
    "UsoCFDI": null,
    "Contacto": {
        "Nombre": "Hugo",
        "Apellidos": "Boss",
        "Email": "[email protected]",
        "Email2": null,
        "Email3": null,
        "Telefono": "8116121234"
    },
    "UID": "68dff68ab068a",
    "cfdis": 0,
    "cuentas_banco": [],
    "id": "68dff68a579fd64f9fcfbf54"
}

Get Client Billing Information

This endpoint retrieves billing information for clients associated with a specific user and country.

💻
Visit our API Reference to test this endpoint.

Endpoint

GET https://pay.ecart.com/api/billings/clients
GET https://sandbox.ecartpay.com/api/billings/clients

Headers

Authorization: {token}

Query Parameters

Key	Type	Description
`user`	String	User identifier (e.g., `590475`)
`country`	String	Country code (e.g., `MX` for Mexico)

Examples

Request

curl --location 'https://pay.ecart.com/api/billings/clients?user=590475&country=MX' \
--header 'authorization: token'

Response

{
    "count": 0,
    "docs": [],
    "pages": 0
}

Ecart Pay user interface Client Billing Information page example.

Get Client Billing Invoices

This endpoint retrieves a list of invoices associated with registered clients.

💻
Visit our API Reference to test this endpoint.

Endpoint

GET https://pay.ecart.com/api/invoices
GET https://sandbox.ecartpay.com/api/invoices

Headers

Authorization: {token}

Query Parameters

Parameter	Description
`year`	Year of the invoices (e.g., 2023).
`month`	Month of the invoices (e.g., August).
`page`	Page number for pagination (default: 1).
`limit`	Number of invoices per page (default: 20).

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/invoices?year=2025&month=5&page=1&limit=10' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI4MTE2MTI2NzY3IiwiY291bnRyeSI6Ik1YIiwiY3VycmVuY3kiOiJNWE4iLCJ2ZXJpZmllZCI6dHJ1ZSwiYWN0aXZlIjp0cnVlfSwiaWF0IjoxNzU5Nzg2NTA3LCJleHAiOjE3NTk3OTAxMDd9.L_opsS6a2bsEL3M5gZx17MjSN4aJje-ESWXYizFnEmP2WN9LXEhnipR5uZBoq4rvDsc5KVyGu4h0pnM5Woypqw' \
--header 'Cookie: lang=en'

Response

{
    "count": 0,
    "pages": 0,
    "docs": []
}

Get Order Invoice Creation

💻
Visit our API Reference to test this endpoint.

Endpoints

GET https://pay.ecart.com/api/orders/public
GET https://sandbox.ecartpay.com/api/orders/public

Header

Authorization: token

Path Parameters

order_id

Examples

Response

curl --location 'https://pay.ecart.com/api/orders/public/68d198e4d71e7b5538c5fc36' \
--header 'authorization: token'

Request

{
    "id": "68d198e4d71e7b5538c5fc36",
    "first_name": "Marcelo von B",
    "number": "OR0016820882",
    "totals": {
        "subtotal": 250,
        "total": 250,
        "tax": 0,
        "discount": 0,
        "shipping": 0
    },
    "currency": "MXN",
    "status": "created",
    "items": [
        {
            "name": "SERVICIO LOGISTICO DE ENVIO",
            "quantity": 1,
            "price": 250,
            "discount": 0,
            "total": 250,
            "tax": 0,
            "fiscal_code": "78102200",
            "unit_code": "E48",
            "is_service": true,
            "taxes": []
        }
    ],
    "shipping_items": [],
    "payments": [],
    "created_at": "2025-09-22T18:43:48.411Z"
}