How to use this API?

Overview

This guide provides a step-by-step walkthrough for integrating with Lia’s checkout system. By following this process, you will create products, configure offers with payment options, and share checkout links with your customers.

The integration follows this workflow:

List available kinds and shifts
Create a product
Create an offer with payment configurations
Share the offer URL with your customers
Set up webhooks to receive event notifications (optional)

Prerequisites

Before you begin, ensure you have:

A valid API token for authentication
Access to the external API endpoints (sandbox or production)
The base URL for your environment:
- Sandbox: https://external-api-sandbox.lia.com.br
- Production: https://external-api.lia.com.br

All requests must include an Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Step 1: List Available Kinds

Kinds represent the type or category of your product (e.g., Course, Event, Mentorship, eBook, Template).

Request

curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/kinds' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Response

[
  {
    "id": "95c7a40c-fe12-4459-bc53-7a16cf6b2493",
    "name": "Curso"
  },
  {
    "id": "3dc875cd-a61f-4e08-963d-2b6fa9686f86",
    "name": "Evento"
  },
  {
    "id": "b84e388d-9a38-4111-a574-c4e6aa07a6a4",
    "name": "Mentoria"
  },
  {
    "id": "8a145abf-9463-4088-bbd0-978c3a1312cf",
    "name": "eBook"
  },
  {
    "id": "34f575df-d133-41fe-b981-33b02bc09a4b",
    "name": "Arquivo/Template"
  }
]

Action: Select the id of the kind that best fits your product. For this example, we’ll use:

kind_id: 95c7a40c-fe12-4459-bc53-7a16cf6b2493 (Curso)

Step 2: List Available Shifts

Shifts represent the schedule or timing of your product (e.g., Morning, Afternoon, Evening, Online).

Request

curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/shifts' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Response

[
  {
    "id": "7b062161-db67-4ae4-b591-1ee242dcebb3",
    "name": "Online"
  },
  {
    "id": "ffffcf81-fada-5b2e-bec3-ecbbac9fea04",
    "name": "Matutino"
  },
  {
    "id": "a6d32eff-195d-5f8b-8467-27f3d34dd847",
    "name": "Vespertino"
  }
]

Action: Select the id of the shift that best fits your product. For this example, we’ll use:

shift_id: 7b062161-db67-4ae4-b591-1ee242dcebb3 (Online)

Step 3: Create a Product

A product represents what you are selling. You must specify the full price, access period, and other details.

Access Period Options

lifetime: Product access never expires
days: Access expires after a specified number of days (requires duration_in_days)
period: Access is available within a specific date range (requires start_date and end_date)
undefined_period: Access period is not yet defined

Request

curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/products' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
  "name": "Complete Web Development Course",
  "full_amount_cents": 299700,
  "kind_id": "95c7a40c-fe12-4459-bc53-7a16cf6b2493",
  "shift_id": "7b062161-db67-4ae4-b591-1ee242dcebb3",
  "access_period": "days",
  "duration_in_days": 365,
  "description": "Learn full-stack web development with React, Node.js, and PostgreSQL. Includes 100+ hours of video content, projects, and lifetime support.",
  "meta_pixel_code": "1234567890",
  "google_pixel_code": "GTM-XXXXXXX",
  "metadata": {
    "course_level": "intermediate",
    "language": "pt-BR",
    "instructor": "John Doe"
  }
}'

Request Parameters

Parameter	Description	Required	Type
`name`	Name of your product	Yes	String
`full_amount_cents`	Full price in cents (between 500 and 500000000)	Yes	Integer
`kind_id`	Kind unique identifier from Step 1	Yes	String
`shift_id`	Shift unique identifier from Step 2	Yes	String
`access_period`	Access period type: `days`, `period`, `lifetime`, or `undefined_period`	Yes	String
`duration_in_days`	Number of days of access (required if `access_period` is `days`)	Conditional	Integer
`duration_in_hours`	Total duration in hours	No	Integer
`start_date`	Start date in ISO8601 format (required if `access_period` is `period`)	Conditional	String
`end_date`	End date in ISO8601 format (required if `access_period` is `period`)	Conditional	String
`description`	Product description	No	String
`meta_pixel_code`	Meta Pixel ID for tracking	No	String
`google_pixel_code`	Google Tag Manager ID for tracking	No	String
`metadata`	Additional data for your integration	No	Object
`banner`	Product image (PNG, JPEG, WEBP, max 500kB)	No	File

Response

{
  "id": "ce375417-b11a-527a-85f1-30d1202cd5c3",
  "name": "Complete Web Development Course",
  "full_amount_cents": 299700,
  "full_amount_currency": "BRL",
  "created_at": "2024-03-15T14:30:07.673-03:00",
  "description": "Learn full-stack web development with React, Node.js, and PostgreSQL. Includes 100+ hours of video content, projects, and lifetime support.",
  "availability": "enabled",
  "duration_in_hours": null,
  "access_period": "days",
  "duration_in_days": 365,
  "start_date": null,
  "end_date": null,
  "meta_pixel_code": "1234567890",
  "google_pixel_code": "GTM-XXXXXXX",
  "banner_url": null,
  "updated_at": "2024-03-15T14:30:07.673-03:00",
  "metadata": {
    "course_level": "intermediate",
    "language": "pt-BR",
    "instructor": "John Doe"
  },
  "company_id": "6883d1f9-0cf0-5167-a6bd-fc57b08454a5",
  "formatted_access_period": "365 dias",
  "kind": {
    "id": "95c7a40c-fe12-4459-bc53-7a16cf6b2493",
    "name": "Curso"
  },
  "shift": {
    "id": "7b062161-db67-4ae4-b591-1ee242dcebb3",
    "name": "Online"
  },
  "offers": []
}

Action: Save the product id from the response. For this example:

product_id: ce375417-b11a-527a-85f1-30d1202cd5c3

Step 4: Create an Offer with Payment Configurations

An offer defines how customers can purchase your product. It includes the price and available payment methods.

Understanding Payment Configurations

There are two main payment types:

1. Upfront Payment

Customer pays the full amount immediately (in one or multiple installments).

Example configurations:

PIX (instant payment, single installment)
Credit Card (up to X installments with interest)

2. Financed Payment

Customer makes a down payment, then pays the remaining balance in installments over time.

Financed types:

bolepix: Down payment via PIX or credit card; installments via boleto or PIX
card: Down payment and installments via credit card only

Request

curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/offers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
  "offer": {
    "product_id": "ce375417-b11a-527a-85f1-30d1202cd5c3",
    "name": "Standard Payment Plan",
    "amount_cents": 299700
  },
  "payment_configurations": [
    {
      "payment_type": "upfront",
      "payment_methods": ["pix"],
      "expires_in_hours": 72
    },
    {
      "payment_type": "upfront",
      "payment_methods": ["credit_card"],
      "expires_in_hours": 24,
      "interest_rate": 0.0149,
      "max_installments": 12
    },
    {
      "payment_type": "financed",
      "financed_type": "bolepix",
      "allowed_down_payment_methods": ["pix", "credit_card"],
      "payment_methods": ["pix", "boleto"],
      "expires_in_hours": 48,
      "interest_rate": 0.0399,
      "max_installments": 24,
      "down_payment_type": "percentage",
      "down_payment_value": 0.2,
      "down_payment_interest_rate": 0.0,
      "fee_embedded_in_down_payment": true
    }
  ]
}'

Payment Configuration Parameters

Parameter	Description	Required	Type
`payment_type`	Payment type: `upfront` or `financed`	Yes	String
`payment_methods`	Array of payment methods: `pix`, `boleto`, `credit_card`. Required for `upfront`; for `financed` it defaults to all three	Conditional	Array
`expires_in_hours`	Hours until payment expires (maximum 240). Defaults to the company default	No	Integer
`interest_rate`	Monthly interest rate (e.g., 0.0149 = 1.49% per month)	Conditional	Float
`max_installments`	Maximum number of installments	Conditional	Integer
`financed_type`	Type of financing: `bolepix` or `card` (required if `payment_type` is `financed`)	Conditional	String
`allowed_down_payment_methods`	Array of methods for down payment (required if `payment_type` is `financed`)	Conditional	Array
`down_payment_type`	Down payment calculation: `percentage` or `absolute`. When not sent, the company default down payment is used	No	String
`down_payment_value`	Down payment amount: a fraction for `percentage` (e.g. `0.2` for 20%) or cents for `absolute`	No	Float/Integer
`down_payment_interest_rate`	Interest rate for down payment installments	No	Float
`max_down_payment_installments`	Maximum number of credit card installments for the down payment	No	Integer
`fee_embedded_in_down_payment`	Whether registration fee is included in down payment	No	Boolean

Response

{
  "id": "c013d81e-57e9-519e-8f3b-8d161568dbca",
  "name": "Standard Payment Plan",
  "amount_cents": 299700,
  "amount_currency": "BRL",
  "availability": "enabled",
  "created_at": "2024-03-15T15:45:23.456-03:00",
  "updated_at": "2024-03-15T15:45:23.456-03:00",
  "url": "https://pague-sandbox.lia.com.br/lia/oferta?offer_id=c013d81e-57e9-519e-8f3b-8d161568dbca",
  "smart_payment_enabled": false,
  "checkout_type": "default",
  "expires_at": null,
  "seats": null,
  "payment_configurations": [
    {
      "id": "1aaee0e3-eb78-5984-83bc-8b41fa289755",
      "payment_type": "upfront",
      "payment_methods": [
        "pix"
      ],
      "expires_in": 72,
      "financed_type": null,
      "interest_rate": "0.0",
      "max_installments": 1,
      "min_installment_amount_cents": 0,
      "allowed_down_payment_methods": [],
      "down_payment_type": null,
      "down_payment_value": 0.0,
      "down_payment_interest_rate": null,
      "max_down_payment_installments": null,
      "registration_fee": 0.0,
      "take_rate_type": "absolute",
      "take_rate_value": "297.0",
      "availability": "enabled",
      "fee_embedded_in_down_payment": false,
      "max_amount_cents": null
    },
    {
      "id": "1aaee0e3-eb78-5984-83bc-8b41fa289755",
      "payment_type": "upfront",
      "payment_methods": [
        "credit_card"
      ],
      "expires_in": 72,
      "financed_type": null,
      "interest_rate": "0.0149",
      "max_installments": 12,
      "min_installment_amount_cents": 1000,
      "allowed_down_payment_methods": [],
      "down_payment_type": null,
      "down_payment_value": 0.0,
      "down_payment_interest_rate": null,
      "max_down_payment_installments": null,
      "registration_fee": 0.0,
      "take_rate_type": "percentage",
      "take_rate_value": "0.0297",
      "availability": "enabled",
      "fee_embedded_in_down_payment": false,
      "max_amount_cents": null
    },
    {
      "id": "eff875a9-ac27-54a1-b1cd-57d89b336cb0",
      "payment_type": "financed",
      "payment_methods": [
        "pix",
        "boleto"
      ],
      "expires_in": 48,
      "financed_type": "bolepix",
      "interest_rate": 0.0399,
      "max_installments": 24,
      "min_installment_amount_cents": 5000,
      "allowed_down_payment_methods": [
        "pix",
        "credit_card"
      ],
      "down_payment_type": "percentage",
      "down_payment_value": 0.2,
      "down_payment_interest_rate": 0.0,
      "max_down_payment_installments": 4,
      "registration_fee": 0.0297,
      "take_rate_type": "percentage",
      "take_rate_value": 0.08,
      "availability": "enabled",
      "fee_embedded_in_down_payment": true,
      "max_amount_cents": null
    }
  ],
  "product": {
    "id": "ce375417-b11a-527a-85f1-30d1202cd5c3",
    "name": "Complete Web Development Course",
    "full_amount_cents": 299700,
    "full_amount_currency": "BRL",
    "created_at": "2024-03-15T14:30:07.673-03:00",
    "description": "Learn full-stack web development with React, Node.js, and PostgreSQL. Includes 100+ hours of video content, projects, and lifetime support.",
    "availability": "enabled",
    "duration_in_hours": null,
    "access_period": "days",
    "duration_in_days": 365,
    "start_date": null,
    "end_date": null,
    "meta_pixel_code": "1234567890",
    "google_pixel_code": "GTM-XXXXXXX",
    "banner_url": null,
    "updated_at": "2024-03-15T14:30:07.673-03:00",
    "metadata": {
      "course_level": "intermediate",
      "language": "pt-BR",
      "instructor": "John Doe"
    },
    "company_id": "6883d1f9-0cf0-5167-a6bd-fc57b08454a5",
    "formatted_access_period": "365 dias",
    "kind": {
      "id": "95c7a40c-fe12-4459-bc53-7a16cf6b2493",
      "name": "Curso"
    },
    "shift": {
      "id": "7b062161-db67-4ae4-b591-1ee242dcebb3",
      "name": "Online"
    }
  }
}

Action: Copy the url field from the response. This is the checkout link you will share with your customers:

https://pague-sandbox.lia.com.br/lia/oferta?offer_id=c013d81e-57e9-519e-8f3b-8d161568dbca

The offer URL is the checkout page where customers can complete their purchase. You can:

Send via email or SMS: Include the URL in customer communications
Embed on your website: Add a “Buy Now” button that links to the URL
Share on social media: Post the link directly for customers to access

When customers visit the URL, they will:

See the product details and available payment options
Select their preferred payment method
Fill in their personal information
Complete the purchase

When testing the checkout in sandbox, no e-mail or SMS is sent. Enter 123456 whenever a verification code is requested. See Environments.

Step 6: Set Up Webhooks (Optional but Recommended)

Webhooks allow you to receive real-time notifications when events occur (e.g., order created, payment received, billing completed).

Available Entities and Events

Entity	Events	Description
`order`	`in_progress`, `finished`, `canceled`, `access_revoked`, `access_restored`	Order lifecycle events
`billing`	`waiting_payment`, `active`, `finished`, `canceled`	Billing status changes
`bill`	`pending`, `paid`, `canceled`, `overdue`	Individual bill payment events

Request

curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
  "name": "Order Status Webhook",
  "url": "https://your-domain.com/webhooks/lia/orders",
  "entity": "order",
  "events": ["finished", "canceled"],
  "verb": "post"
}'

Request Parameters

Parameter	Description	Required	Type
`name`	Descriptive name for the webhook	Yes	String
`url`	Your endpoint URL that will receive webhook notifications. Must be a public `https://` URL	Yes	String
`entity`	Entity type: `order`, `billing`, or `bill`	Yes	String
`events`	Array of events to listen for	Yes	Array
`verb`	HTTP method: `post`, `put` or `get` (recommended: `post`)	Yes	String

Response

{
  "id": "c6513893-c0ed-56bc-ab8e-fc581d390135",
  "name": "Order Status Webhook",
  "url": "https://your-domain.com/webhooks/lia/orders",
  "entity": "order",
  "events": [
    "finished",
    "canceled"
  ],
  "target": "standard",
  "params": null,
  "verb": "post",
  "created_at": "2024-03-15T16:00:00.000-03:00",
  "updated_at": "2024-03-15T16:00:00.000-03:00"
}

Webhook Payload Example

When an event occurs, Lia will send a POST request to your webhook URL with the following payload (data abbreviated; see Order Events for the full payload):

{
  "api_version": "1.0",
  "entity": "order",
  "event": "finished",
  "data": {
    "id": "3c6d7169-75c1-567f-9b78-09657791d725",
    "status": "finished",
    "customer_name": "João Silva",
    "customer_document": "12345678901",
    "customer_type": "person",
    "offer": {
      "id": "c013d81e-57e9-519e-8f3b-8d161568dbca",
      "name": "Standard Payment Plan",
      "amount_cents": 299700,
      "product": {
        "id": "ce375417-b11a-527a-85f1-30d1202cd5c3",
        "name": "Complete Web Development Course",
        "description": "Learn full-stack web development with React, Node.js, and PostgreSQL. Includes 100+ hours of video content, projects, and lifetime support."
      }
    },
    "billings": [
      {
        "id": "3e6575aa-4b78-5e12-83ad-2f96b23aef37",
        "status": "active",
        "amount_cents": 299700,
        "installments": 24
      }
    ],
    "created_at": "2024-03-15T17:30:00.000-03:00",
    "finished_at": "2024-03-15T17:35:00.000-03:00",
    "contact": {
      "email": "joao.silva@example.com",
      "phone": "5511999999999"
    },
    "order_bump_offers": []
  },
  "id": "9b2f6a3c1d8e4f5a6b7c8d9e0f1a2b3c"
}

Best Practices:

Return a 200 OK response immediately upon receiving the webhook
Process the webhook data asynchronously to avoid timeouts
Validate the webhook data before processing
Implement retry logic in case of temporary failures
Store webhook delivery history for debugging

Common Scenarios

Scenario 1: Simple Product with PIX Payment Only

# Create product
curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/products' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
  "name": "eBook: Digital Marketing Guide",
  "full_amount_cents": 4900,
  "kind_id": "8a145abf-9463-4088-bbd0-978c3a1312cf",
  "shift_id": "7b062161-db67-4ae4-b591-1ee242dcebb3",
  "access_period": "lifetime",
  "description": "Complete guide to digital marketing in 2024"
}'

# Create offer with PIX only
curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/offers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
  "offer": {
    "product_id": "PRODUCT_ID_FROM_PREVIOUS_RESPONSE",
    "name": "PIX Payment",
    "amount_cents": 4900
  },
  "payment_configurations": [
    {
      "payment_type": "upfront",
      "payment_methods": ["pix"],
      "expires_in_hours": 48
    }
  ]
}'

Scenario 2: High-Value Course with Flexible Payment Options

# Create offer with multiple payment options
curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/offers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--data '{
  "offer": {
    "product_id": "ce375417-b11a-527a-85f1-30d1202cd5c3",
    "name": "Flexible Payment Options",
    "amount_cents": 299700
  },
  "payment_configurations": [
    {
      "payment_type": "upfront",
      "payment_methods": ["pix"],
      "expires_in_hours": 72
    },
    {
      "payment_type": "upfront",
      "payment_methods": ["credit_card"],
      "expires_in_hours": 24,
      "interest_rate": 0.0199,
      "max_installments": 12
    },
    {
      "payment_type": "financed",
      "financed_type": "bolepix",
      "allowed_down_payment_methods": ["pix"],
      "payment_methods": ["pix", "boleto"],
      "expires_in_hours": 48,
      "interest_rate": 0.0299,
      "max_installments": 18,
      "down_payment_type": "percentage",
      "down_payment_value": 0.15
    }
  ]
}'

Monitoring Your Sales

After setting up your integration, you can monitor orders and payments through the API:

List All Orders

curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/orders' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Get Specific Order Details

curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/orders/ORDER_ID' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

List All Billings

curl --location 'https://external-api-sandbox.lia.com.br/external_api/v1/billings' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Error Handling

The API uses standard HTTP status codes:

Status Code	Description
`200`	Success
`201`	Resource created successfully
`400`	Bad request (invalid parameters)
`401`	Unauthorized (invalid or missing API token), with an empty body `{}`
`403`	Forbidden (access denied, or blocked IP)
`404`	Resource not found
`422`	Unprocessable entity (validation errors)
`429`	Too many requests (see Rate Limits)
`500`	Internal server error

Example Error Response

Errors return status, error and a messages list, with the messages in Portuguese:

{
  "status": 422,
  "error": "record_invalid",
  "messages": [
    {
      "attribute": "kind",
      "message": "Kind é obrigatório(a)"
    },
    {
      "attribute": "full_amount_cents",
      "message": "Full amount cents deve ser maior ou igual a 500"
    }
  ]
}

Next Steps

Now that you have successfully integrated with Lia’s checkout:

Test the complete flow in the sandbox environment
Implement webhook handlers to process order and payment events
Monitor your integration using the order and billing list endpoints
Switch to production when ready by updating the base URL and API token

For detailed API reference documentation, see:

How to use this API?

Overview

Prerequisites

Step 1: List Available Kinds

Request

Response

Step 2: List Available Shifts

Request

Response

Step 3: Create a Product

Access Period Options

Request

Request Parameters

Response

Step 4: Create an Offer with Payment Configurations

Understanding Payment Configurations

1. Upfront Payment

2. Financed Payment

Request

Payment Configuration Parameters

Response

Step 5: Share the Checkout URL with Your Customers

Step 6: Set Up Webhooks (Optional but Recommended)

Available Entities and Events

Request

Request Parameters

Response

Webhook Payload Example

Common Scenarios

Scenario 1: Simple Product with PIX Payment Only

Scenario 2: High-Value Course with Flexible Payment Options

Monitoring Your Sales

List All Orders

Get Specific Order Details

List All Billings

Error Handling

Example Error Response

Next Steps