Checkout - Chariow Developers

The checkout API allows you to programmatically create purchase sessions for your customers. This is useful for custom storefronts, integrations, or automated sales flows.

Unsupported product types: the following cannot be used to initiate a checkout through the API:

Service products
Coaching products
Products with pay-what-you-want pricing

For these, redirect customers to your Chariow storefront or use the Snap Widget embed on your website.

All sales initiated via the checkout API will have their Channel set to “API” on your store dashboard. This helps you identify and track sales originating from your API integrations separately from other channels like your storefront or Snap Widget.

Repeat Purchases

The ability to purchase a product multiple times depends on the product type:

Product Type	Repeat Purchase	Behaviour
License	Always allowed	Customers can purchase license products multiple times. Each purchase generates a new unique license key.
Downloadable	Blocked	Returns `already_purchased` if customer has an active access grant.
Course	Blocked	Returns `already_purchased` if customer has an active access grant.
Bundle	Blocked	Returns `already_purchased` if customer has an active access grant.

For blocked product types, if a customer’s access has been revoked (e.g., after a refund), they will be able to purchase the product again. The system checks for active access grants only.

Checkout Flow Overview

The Chariow checkout API handles the complete purchase flow from initiation to completion:

The product must be published before initiating a checkout. Unpublished products will return a 404 error.

Initiate Checkout

Call the /checkout endpoint with product ID and customer details

Handle Response

Check the step field in the response:

payment: Redirect customer to checkout_url for payment
completed: Sale completed immediately (free products)
already_purchased: Customer already owns this product

Process Payment

Customer completes payment on the secure hosted payment page, using the methods available in their country

Receive Webhook

Get notified of sale status changes via webhooks (recommended)

Deliver Product

Customer receives automatic access to files, licenses, courses, etc.

Product Types Supported

The checkout API supports the following Chariow product types:

Downloadable Products: Digital files (PDFs, software, media)
Courses: Educational content with lessons and chapters
Licenses: Software license keys with activation management
Bundles: Collections of multiple products

Service and Coaching product types are not supported via the Public API. For these products, redirect customers to your Chariow store or use the Snap Widget. Products using pay-what-you-want pricing are also not supported.

Initiating a Checkout

Create a new checkout session:

curl -X POST "https://api.chariow.com/v1/checkout" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_abc123",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "number": "1234567890",
      "country_code": "US"
    },
    "discount_code": "SAVE20"
  }'

const response = await fetch('https://api.chariow.com/v1/checkout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    product_id: 'prd_abc123',
    email: 'customer@example.com',
    first_name: 'John',
    last_name: 'Doe',
    phone: {
      number: '1234567890',
      country_code: 'US'
    },
    discount_code: 'SAVE20'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.chariow.com/v1/checkout',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'product_id': 'prd_abc123',
        'email': 'customer@example.com',
        'first_name': 'John',
        'last_name': 'Doe',
        'phone': {
            'number': '1234567890',
            'country_code': 'US'
        },
        'discount_code': 'SAVE20'
    }
)

Request Parameters

Parameter	Type	Required	Description
`product_id`	string	Yes	Product public ID or slug (e.g., `prd_abc123xyz` or `premium-course`)
`price_variant_id`	string	No	Identifier of an active price variant (one-time pricing only). An unknown or inactive variant is ignored and the regular price is used
`email`	string	Yes	Customer email address (strict check, max 255 characters). Stored in lowercase
`first_name`	string	Yes	Customer first name (max 50 characters)
`last_name`	string	Yes	Customer last name (max 50 characters)
`phone.number`	string	Yes	Phone number (numeric only)
`phone.country_code`	string	Yes	ISO 3166-1 alpha-2 country code of a known country (e.g., “US”, “CI”, “SN”)
`discount_code`	string	No	Discount code to apply (max 100 characters)
`affiliate_code`	string	No	Affiliate tracking code for commission attribution (max 50 characters)
`campaign_id`	string	No	Campaign public ID or tracking code
`custom_fields`	object	No	Custom field values (key-value pairs)
`payment_currency`	string	No	ISO 4217 code of a currency supported by Chariow (e.g., “XOF”, “EUR”). Defaults to your store currency. See Multi-Currency Support
`redirect_url`	string	No	Custom redirect URL after payment completion (max 2048 characters)
`custom_metadata`	object	No	Custom key-value metadata to store with the sale (max 10 keys, 255 chars per value). Included in Pulse webhook payloads.
`customer_ip`	string	No	The buyer’s IP address, IPv4 or IPv6 (e.g., “203.0.113.42”). See Buyer IP address.
`embed_origins`	array	No	Up to 4 HTTPS origins allowed to embed the payment page in an iframe. See Embedding the Payment Page
`gift`	object	No	Buy the product for someone else. See Gift Purchases
`shipping`	object	Conditional	Shipping address, required when the product requires one. See below

Shipping Address Fields

When the product has “Require shipping address” enabled, you must send a shipping object in your checkout request:

Parameter	Type	Required	Description
`shipping.address`	string	Conditional	Street address for shipping
`shipping.city`	string	Conditional	City for shipping
`shipping.state`	string	Conditional	State or region for shipping
`shipping.country`	string	Conditional	Country code of a known country (ISO 3166-1 alpha-2, e.g., “US”, “FR”)
`shipping.zip`	string	Conditional	Postal/ZIP code for shipping

These fields are required only when the product has shipping enabled. If shipping is not required, the shipping object is ignored. Address fields sent at the top level of the request body are not read.

Example with Shipping Address

{
  "product_id": "prd_abc123xyz",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "shipping": {
    "address": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "zip": "10001"
  }
}

Checkout Response States

The checkout response includes a step field indicating the current state:

Awaiting Payment

For paid products, you’ll receive a payment URL:

{
  "data": {
    "step": "payment",
    "message": null,
    "purchase": {
      "id": "sal_xyz789",
      "status": "awaiting_payment",
      "amount": {
        "value": 79.20,
        "formatted": "$79.20",
        "short": "79",
        "currency": "USD"
      }
    },
    "payment": {
      "checkout_url": "https://payment.example.com/checkout/abc123?country=US&phone=...",
      "transaction_id": "txn_def456",
      "gateway": "orqex"
    }
  }
}

The purchase object is truncated here; it has the same shape as a sale returned by List Sales.

Redirect the customer to checkout_url to complete their payment. The URL carries the buyer’s phone country and number as query parameters so the payment form is prefilled: use it exactly as returned. gateway identifies the payment gateway handling the payment; treat it as an opaque string.

Completed (Free Products)

For free products, the sale completes immediately:

{
  "data": {
    "step": "completed",
    "message": null,
    "purchase": {
      "id": "sal_xyz789",
      "status": "completed"
    },
    "payment": {
      "checkout_url": null,
      "transaction_id": null,
      "gateway": null
    }
  }
}

A paid product also completes immediately when a discount brings the amount to zero.

Already Purchased

If the customer already owns the product:

{
  "data": {
    "step": "already_purchased",
    "message": "You already own this product. Access it in your Customer Portal.",
    "purchase": null,
    "payment": {
      "checkout_url": null,
      "transaction_id": null,
      "gateway": null
    }
  }
}

No sale is created in this case.

Custom Redirect URLs

You can specify a custom redirect URL to send customers to your own thank-you page after payment completion:

curl -X POST "https://api.chariow.com/v1/checkout" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_abc123xyz",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "number": "1234567890",
      "country_code": "US"
    },
    "redirect_url": "https://yoursite.com/thank-you?sale={sale_id}"
  }'

The redirect URL must be a valid active URL (max 2048 characters). When not provided, customers will be redirected to the default Chariow post-purchase page.

Multi-Currency Support

Specify the payment currency to charge customers in a different currency from your store’s default:

{
  "product_id": "prd_abc123xyz",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "payment_currency": "EUR"
}

The response will include exchange rate information when currency conversion is applied.

The code must be a currency supported by Chariow. An unsupported code returns a 422 validation error on payment_currency instead of starting the checkout
When the payment currency differs from the product currency, the price is converted and a conversion markup is added. The markup rate depends on the payment currency and is the same one applied to prices shown on your storefront, so the buyer pays the amount they were shown
The sale amounts (amount, original_amount) stay in the product currency; purchase.payment.amount is what the buyer pays, in the payment currency

Applying Discount Codes

Pass a discount code to apply savings:

{
  "product_id": "prd_abc123xyz",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "discount_code": "SAVE20"
}

The response will show the discounted amount:

{
  "data": {
    "purchase": {
      "original_amount": {
        "value": 99,
        "formatted": "$99.00",
        "short": "99",
        "currency": "USD"
      },
      "amount": {
        "value": 79.20,
        "formatted": "$79.20",
        "short": "79",
        "currency": "USD"
      },
      "discount_amount": {
        "value": 19.80,
        "formatted": "$19.80",
        "short": "20",
        "currency": "USD"
      },
      "discount": {
        "id": "dis_xyz789",
        "name": "Save 20%",
        "code": "SAVE20"
      }
    }
  }
}

Custom Fields

If your product has custom fields configured, you can collect and validate them during checkout:

{
  "product_id": "prd_abc123xyz",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "custom_fields": {
    "company_name": "Acme Corp",
    "job_title": "Developer",
    "team_size": "10-50"
  }
}

Custom fields must match the product’s configured custom field definitions. Invalid or missing required custom fields will result in validation errors.

Campaign Tracking

Track the source of sales by including a campaign ID:

{
  "product_id": "prd_abc123xyz",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "campaign_id": "camp_summer2024"
}

This helps you:

Track which marketing campaigns drive the most sales
Attribute revenue to specific channels
Analyse campaign performance in your Chariow dashboard

Custom Metadata

Store custom data with the sale for your own tracking and integration purposes:

{
  "product_id": "prd_abc123xyz",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "custom_metadata": {
    "order_ref": "ORD-123",
    "source": "landing_page",
    "utm_campaign": "summer_sale"
  }
}

Important Notes

Maximum 10 keys allowed per sale
Each value is limited to 255 characters
Keys should be strings with alphanumeric characters and underscores
Custom metadata is included in Pulse webhook payloads

Use custom metadata to link Chariow sales with your CRM, analytics platform, or internal systems. The metadata is returned in all sale-related webhooks.

Buyer IP Address

The checkout endpoint is called from your server, so the IP address we observe is your own infrastructure, not the buyer’s. Pass the buyer’s IP in customer_ip to correct that:

{
  "product_id": "prd_abc123xyz",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "customer_ip": "203.0.113.42"
}

Read the buyer’s IP from the request that reaches your own server, typically the leftmost entry of the X-Forwarded-For header, or CF-Connecting-IP if you sit behind Cloudflare.

What it improves

Payment methods: the buyer’s country is resolved from this IP, and the country determines which payment methods appear on the checkout page
Analytics: sales are attributed to the buyer’s country rather than to your server’s hosting region
Fraud review: the sale record carries the buyer’s real IP

Important notes

The field is optional. Without it, or when the IP cannot be located, the buyer’s country is taken from phone.country_code, never from your server’s location. The sale then records the calling IP as its IP address
Both IPv4 and IPv6 are accepted; a malformed value returns a 422
The field is only honoured on API checkouts, so it cannot be spoofed from a browser

Embedding the Payment Page

To show the hosted payment page inside an iframe on your own site, list the origins that will embed it in embed_origins (up to 4):

{
  "product_id": "prd_abc123xyz",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "embed_origins": ["https://shop.example.com"]
}

Each entry must be a canonical HTTPS origin: lowercase https:// scheme and host, an optional non-default port, and no path, query string, fragment, credentials or trailing slash. https://shop.example.com is valid; https://shop.example.com/, http://shop.example.com and https://Shop.example.com are rejected with a 422.

Gift Purchases

Send a gift object to buy the product for someone else. The recipient receives access to the product, and the buyer pays:

{
  "product_id": "prd_abc123xyz",
  "email": "buyer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": {
    "number": "1234567890",
    "country_code": "US"
  },
  "gift": {
    "recipient_email": "friend@example.com",
    "recipient_first_name": "Jane",
    "recipient_last_name": "Smith",
    "message": "Happy birthday!"
  }
}

Parameter	Type	Required	Description
`gift.recipient_email`	string	Yes (with `gift`)	Recipient email (max 255 characters). Must differ from the buyer’s email, otherwise the API returns `422`
`gift.recipient_first_name`	string	Yes (with `gift`)	Recipient first name (max 50 characters)
`gift.recipient_last_name`	string	Yes (with `gift`)	Recipient last name (max 50 characters)
`gift.message`	string	No	Message for the recipient (max 500 characters)

If the recipient already owns the product, the API returns 409. The sale carries a gift object with the recipient and the message.

Existing Customers

Each store has one customer per email address, compared case-insensitively. When a checkout uses the email of an existing customer, that customer is reused and their first name, last name and phone number are updated with the values sent. The same applies to a gift recipient.

Rate Limits

Checkout has its own rate-limit bucket of 100 requests per minute per API key, separate from the rest of the Public API, so a bulk sync of sales or products cannot block your buyers from paying. Above the limit the API returns 429 Too Many Requests.

Error Handling

Common checkout errors and how to handle them:

HTTP Status	Error	Cause	Solution
400	Invalid phone number	`phone.number` is not valid for `phone.country_code`	Check the number and country code
400	Product sold out	The product’s stock is exhausted, or no licence key is left in stock	Restock the product or its licences
400	Discount not applicable	Discount code inactive, expired, used up, reserved for another customer, or not valid for this product or price variant	Verify the discount code is active and applicable
400	Store cannot sell	Your store is not currently allowed to receive orders	Contact Chariow support
400	Payment could not start	The payment session could not be opened; the sale is marked as failed	Retry the checkout
401	Unauthorised	Invalid or missing API key	Check your API key is correct and included in the `Authorization` header
404	Product not found	Invalid product ID or unpublished product	Verify the product ID/slug exists and is published
404	Discount code not found	No discount with this code in your store	Check the code
409	Recipient already owns the product	Gift recipient already has access to the product	Choose another product or recipient
422	Validation failed	Missing or invalid fields, unsupported `payment_currency`, unknown country code	Check all required fields are provided with correct formats
422	Pay-what-you-want not supported	Product uses pay-what-you-want pricing	Redirect customers to your Chariow store or use the Snap Widget
422	Product type not supported	Product is a Service or Coaching type	Redirect customers to your Chariow store or use the Snap Widget
422	Gift for yourself	Gift recipient email equals the buyer’s email	Use the recipient’s own email
422	Missing shipping address	Product requires shipping but the `shipping` fields are missing	Include `shipping.address`, `shipping.city`, `shipping.state`, `shipping.country` and `shipping.zip`
429	Too many requests	Checkout rate limit exceeded	Retry after a short delay

Errors raised by business rules (400, 404, 409) return a message and an empty errors array. Validation errors (422 with field errors) list each invalid field in errors.

Example Error Response

{
  "message": "The email field must be a valid email address.",
  "data": [],
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ],
    "phone.number": [
      "The phone.number field is required."
    ]
  }
}

Always check the errors object for field-specific validation messages to help users correct their input.

Best Practices

Handle All Response Steps

Always check the step field and handle all possible states:

const response = await fetch('https://api.chariow.com/v1/checkout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(checkoutData)
});

const result = await response.json();

switch (result.data.step) {
  case 'payment':
    // Redirect to payment URL
    window.location.href = result.data.payment.checkout_url;
    break;

  case 'completed':
    // Show success message for free products
    showSuccessMessage(result.data.purchase);
    break;

  case 'already_purchased':
    // Inform customer they already own this product
    showAlreadyPurchasedMessage(result.data.message);
    break;
}

Use Pulses for Sale Updates

Don’t rely solely on redirect URLs to track sale completion. Set up Pulses (webhooks) to receive reliable notifications:

Sale completed
Payment received
Refund processed

See the Pulses Guide for setup instructions.

Validate Before Checkout

Reduce failed checkouts by validating data before calling the API:

Email format validation
Phone number format validation
Required field checks
Custom field validation

Handle Network Errors

Implement proper error handling for network issues:

try {
  const response = await fetch('https://api.chariow.com/v1/checkout', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(checkoutData)
  });

  if (!response.ok) {
    const error = await response.json();
    handleCheckoutError(error);
    return;
  }

  const data = await response.json();
  handleCheckoutSuccess(data);

} catch (error) {
  // Handle network errors
  console.error('Checkout failed:', error);
  showErrorMessage('Unable to process checkout. Please try again.');
}

Store Sale IDs

Always store the returned sale ID (purchase.id) for:

Customer service inquiries
Refund processing
Access management
Analytics tracking

Test with Different Scenarios

Test your integration with:

Free products (immediate completion)
Paid products (payment flow)
Products with discount codes
Products with custom fields
Products that require a shipping address
Products with limited stock
Invalid product IDs
Invalid discount codes

Next Steps

Sales Guide

Learn how to retrieve and manage sales

Pulses

Set up notifications for completed sales

Checkout API

View the complete Checkout API reference

​Repeat Purchases

​Checkout Flow Overview

​Product Types Supported

​Initiating a Checkout

​Request Parameters

​Shipping Address Fields

​Example with Shipping Address

​Checkout Response States

​Awaiting Payment

​Completed (Free Products)

​Already Purchased

​Custom Redirect URLs

​Multi-Currency Support

​Applying Discount Codes

​Custom Fields

​Campaign Tracking

​Custom Metadata

​Important Notes

​Buyer IP Address

​What it improves

​Important notes

​Embedding the Payment Page

​Gift Purchases

​Existing Customers

​Rate Limits

​Error Handling

​Example Error Response

​Best Practices

​Handle All Response Steps

​Use Pulses for Sale Updates

​Validate Before Checkout

​Handle Network Errors

​Store Sale IDs

​Test with Different Scenarios

​Next Steps

Sales Guide

Pulses

Checkout API

Repeat Purchases

Checkout Flow Overview

Product Types Supported

Initiating a Checkout

Request Parameters

Shipping Address Fields

Example with Shipping Address

Checkout Response States

Awaiting Payment

Completed (Free Products)

Already Purchased

Custom Redirect URLs

Multi-Currency Support

Applying Discount Codes

Custom Fields

Campaign Tracking

Custom Metadata

Important Notes

Buyer IP Address

What it improves

Important notes

Embedding the Payment Page

Gift Purchases

Existing Customers

Rate Limits

Error Handling

Example Error Response

Best Practices

Handle All Response Steps

Use Pulses for Sale Updates

Validate Before Checkout

Handle Network Errors

Store Sale IDs

Test with Different Scenarios

Next Steps