Carts

The cart is the entry point of the APIO subscription checkout flow. From your backend, you initialize a cart with one or more products and receive a personalized URL to which you redirect your user to complete the subscription.

---

When to use the cart?

Use case	Example
Subscription checkout from your e-commerce	The user selects a recurrent plan and pays via APIO
Pre-filling buyer data	Reduce subscription checkout friction by sending name, ID and address

---

General flow

1. Your backend calls POST /api/v1/carts/private/initialize with the products.
2. APIO returns a checkout URL containing a cartToken valid for 30 minutes.
3. You redirect the user to that URL. If they don't have an APIO account, they can create one within the same flow.
4. Once the subscription or payment is completed, APIO notifies your backend via webhook.

---

Quick example

const response = await fetch(
  "https://app.apio.cl/api/v1/carts/private/initialize",
  {
    method: "POST",
    headers: {
      "apikey": process.env.APIO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      products: [
        {
          externalReferenceField: "variantSku",
          externalReferenceValue: "S00030135",
          quantity: 1,
          billingType: "monthly",
          singlePrice: 36990,
        },
      ],
    }),
  }
);

const { data } = await response.json();
// Redirect the user:
window.location.href = data;

---

Prerequisites

Before calling the endpoint, make sure you have:

• A valid API Key with permissions on carts. You can obtain one from your APIO dashboard Configuración → Tiendas → API Keys.
• Products registered in the APIO catalog with the external reference field configured (variantSku, sku, externalId, etc.).
• The billingType you intend to send must be enabled for that product in the catalog.

---

billingType: available frequencies

The billingType field defines how often the customer is charged. The available values are:

Value	Frequency
"weekly"	Weekly
"biweekly"	Every 2 weeks
"monthly"	Monthly
"bimonthly"	Every 2 months
"quarterly"	Every 3 months
"biyearly"	Every 6 months
"yearly"	Yearly

If the product does not support the billingType sent, the system will return a 400 error.

---

Important notes

singlePrice vs. finalPrice At least one of the two is required per product.

• singlePrice: unit price. APIO validates it against the catalog price.
• finalPrice: total price (unit × quantity with discounts). APIO calculates it and compares it with your value.
• You can send both; they are validated independently.

expirationCycles

• If omitted: the subscription is indefinite (no automatic end date).
• If provided (e.g. 10): the subscription automatically expires after that number of successful billing cycles.

cartToken validity

• The URL returned in data expires in 30 minutes.
• If the user does not complete the checkout within that time, call the endpoint again to generate a new URL.

---

Next steps

• Set up a webhook to receive notifications when the payment is completed or fails.
• Check the Subscriptions API to manage the lifecycle of the generated subscriptions.