Checkout with multiple products

This example shows a real-world e-commerce scenario: a cart with multiple items, shipping, discount, and payment -- including the correct value calculation for installments.

INFO

The examples use sandbox URLs. For production, replace sandboxappmax with appmax.

Scenario

The customer's cart contains:

Product	Qty	Unit price	Subtotal
T-shirt S	2	R$ 79.90	R$ 159.80
Cap	1	R$ 45.00	R$ 45.00

• Subtotal: R$ 204.80
• Shipping: R$ 18.50
• Discount coupon: R$ 20.00
• Total: R$ 203.30
• Payment: 3 installments on credit card

Prerequisites

• Valid authentication token (how to obtain)
• Customer's customer_id with registered address (how to create)

---

1. Look up installments for the total value

The base value for installment calculation is subtotal + shipping - discount:

20480 + 1850 - 2000 = 20330 cents

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/payments/installments \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "installments": 3,
  "total_value": 20330,
  "settings": true
}'

{
  "data": {
    "installments": {
      "1": { "total": 20330 },
      "2": { "total": 20736 },
      "3": { "total": 21147 }
    },
    "settings": {
      "modality": "PP",
      "max_installments": 12,
      "min_installment_value": 500
    }
  }
}

The customer chooses 3 installments -> total with interest: R$ 211.47 (21147 cents).

2. Distribute interest across products

The interest is R$ 8.17 (21147 - 20330 + 2000 - 1850 = 817 additional cents on the original subtotal). Distribute proportionally:

const produtos = [
  { sku: 'CAM-P', nome: 'Camiseta P', qtd: 2, valorOriginal: 7990 },
  { sku: 'BONE-01', nome: 'Boné', qtd: 1, valorOriginal: 4500 }
];

const subtotalOriginal = 20480; // 159,80 + 45,00
const totalComJuros = 21147;
const frete = 1850;
const desconto = 2000;

// Product value we need to send:
// totalComJuros - frete + desconto = adjusted product value
// Since we use products_value, we send the adjusted total
const productsValue = totalComJuros - frete + desconto;
// 21147 - 1850 + 2000 = 21297

TIP

Use products_value to send the total product value with interest already included. This way you don't need to recalculate each unit_value individually.

3. Create the order

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/orders \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "customer_id": 2023,
  "products_value": 21297,
  "shipping_value": 1850,
  "discount_value": 2000,
  "products": [
    {
      "sku": "CAM-P",
      "name": "Camiseta P",
      "quantity": 2,
      "type": "physical"
    },
    {
      "sku": "BONE-01",
      "name": "Boné",
      "quantity": 1,
      "type": "physical"
    }
  ]
}'

{
  "data": {
    "order": {
      "id": 6001,
      "status": "pendente"
    }
  }
}

WARNING

When using products_value, do not provide unit_value in the products. The two modes are mutually exclusive. See calculation rules for details.

4. Process the payment

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/payments/credit-card \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "order_id": 6001,
  "customer_id": 2023,
  "payment_data": {
    "credit_card": {
      "token": "422146c7523a46119d6073ea56193913",
      "holder_document_number": "25226493029",
      "holder_name": "Junior Almeida",
      "installments": 3,
      "soft_descriptor": "MINHALOJA"
    }
  }
}'

{
  "data": {
    "order": {
      "id": 6001,
      "status": "autorizado"
    },
    "payment": {
      "method": "creditcard",
      "installments": 3,
      "paid_at": "2025-03-15 14:30:00"
    },
    "upsell_hash": "6000114202503117156088040208561001715608804"
  }
}

5. Register the tracking code

Since the order contains physical products, register the tracking code after shipping to release withdrawals:

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/orders/shipping-tracking-code \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "order_id": 6001,
  "shipping_tracking_code": "BR123456789XX"
}'

{
  "data": {
    "message": "tracking accepted"
  }
}

6. Offer an upsell (optional)

After payment, offer a complementary product using the upsell_hash:

curl --request POST \
     --url https://api.sandboxappmax.com.br/v1/orders/upsell \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "upsell_hash": "6000114202503117156088040208561001715608804",
  "products_value": 2990,
  "products": [
    {
      "sku": "MEIA-01",
      "name": "Kit meias esportivas",
      "quantity": 1,
      "unit_value": 2990,
      "type": "physical"
    }
  ]
}'

The upsell is automatically charged to the same card, without the customer needing to enter their details again.

---

Complete flow diagram

---

Value summary

Field	Value	Cents
Subtotal (2 t-shirts + 1 cap)	R$ 204.80	20480
Shipping	R$ 18.50	1850
Discount	-R$ 20.00	2000
Interest (3x)	R$ 8.17	817
Total charged	R$ 211.47	21147
Card installment	3x R$ 70.49	7049