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": "a8c23456-ef78-4de9-bc12-345678901234",
    "name": "Matutino"
  },
  {
    "id": "b9d34567-fg89-5ef0-cd23-456789012345",
    "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 (minimum 500)	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
`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": "8538ab61-1c4f-404b-8cfe-0dbab2bedc09",
  "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": 8760,
  "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": "6cdfdd04-ab2d-48ef-81bf-3e53ebc5644a",
  "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: 8538ab61-1c4f-404b-8cfe-0dbab2bedc09

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": "8538ab61-1c4f-404b-8cfe-0dbab2bedc09",
    "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": 20.0,
      "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`	Yes	Array
`expires_in_hours`	Hours until payment expires	Yes	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` (required if `payment_type` is `financed`)	Conditional	String
`down_payment_value`	Down payment amount (percentage or cents) (required if `payment_type` is `financed`)	Conditional	Float/Integer
`down_payment_interest_rate`	Interest rate for down payment installments	No	Float
`fee_embedded_in_down_payment`	Whether registration fee is included in down payment	No	Boolean

Response

{
  "id": "f429f9de-7f34-4957-93ef-ba9d773be7c5",
  "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=f429f9de-7f34-4957-93ef-ba9d773be7c5",
  "smart_payment_enabled": false,
  "checkout_type": "default",
  "payment_configurations": [
    {
      "id": "4d78071e-5a2d-4622-af97-bf645863f175",
      "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
    },
    {
      "id": "f50a159d-21ee-46cf-a711-c4a5dc074f54",
      "payment_type": "upfront",
      "payment_methods": ["credit_card"],
      "expires_in": 24,
      "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
    },
    {
      "id": "a8b92c5e-3f67-4d21-bc89-e5f67890abcd",
      "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": 20.0,
      "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
    }
  ],
  "product": {
    "id": "8538ab61-1c4f-404b-8cfe-0dbab2bedc09",
    "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": 8760,
    "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": "6cdfdd04-ab2d-48ef-81bf-3e53ebc5644a",
    "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=f429f9de-7f34-4957-93ef-ba9d773be7c5

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

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`	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	Yes	String
`entity`	Entity type: `order`, `billing`, or `bill`	Yes	String
`events`	Array of events to listen for	Yes	Array
`verb`	HTTP method: `post`, `get`, `put`, or `patch` (recommended: `post`)	Yes	String

Response

{
  "id": "d4e56789-gh01-6fg1-de34-567890123456",
  "name": "Order Status Webhook",
  "url": "https://your-domain.com/webhooks/lia/orders",
  "entity": "order",
  "events": ["finished", "canceled"],
  "target": "external_api",
  "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:

{
  "event": "order.finished",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "finished",
    "customer_name": "João Silva",
    "customer_document": "12345678901",
    "customer_type": "person",
    "offer": {
      "id": "f429f9de-7f34-4957-93ef-ba9d773be7c5",
      "name": "Standard Payment Plan"
    },
    "billings": [
      {
        "id": "b8c93d45-67e8-90f1-23g4-567h890i1234",
        "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"
  }
}

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": "8538ab61-1c4f-404b-8cfe-0dbab2bedc09",
    "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.0,
      "max_installments": 6
    },
    {
      "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": 15.0
    }
  ]
}'

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)
`404`	Resource not found
`422`	Unprocessable entity (validation errors)
`500`	Internal server error

Example Error Response

{
  "errors": {
    "full_amount_cents": ["must be greater than or equal to 500"],
    "kind_id": ["can't be blank"]
  }
}

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