Skip to main content
POST
https://api.chariow.com/v1
/
checkout
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": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "number": "1234567890",
      "country_code": "US"
    },
    "discount_code": "SAVE20",
    "redirect_url": "https://yoursite.com/thank-you",
    "custom_metadata": {
      "order_ref": "ORD-123",
      "source": "landing_page"
    }
  }'

{
  "data": {
    "step": "awaiting_payment",
    "message": null,
    "purchase": {
      "id": "sal_abc123xyz",
      "status": "awaiting_payment",
      "original_amount": {
        "amount": 9900,
        "currency": "USD",
        "formatted": "$99.00"
      },
      "amount": {
        "amount": 7920,
        "currency": "USD",
        "formatted": "$79.20"
      },
      "discount_amount": {
        "amount": 1980,
        "currency": "USD",
        "formatted": "$19.80"
      },
      "payment": {
        "amount": {
          "amount": 7920,
          "currency": "USD",
          "formatted": "$79.20"
        },
        "status": "awaiting_payment",
        "exchange_rate": {
          "amount": 100,
          "currency": "USD",
          "formatted": "$1.00"
        }
      },
      "store": {
        "id": "str_xyz789",
        "name": "My Store"
      },
      "product": {
        "id": "prd_abc123xyz",
        "name": "Premium Course",
        "slug": "premium-course"
      },
      "customer": {
        "id": "cus_def456",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe"
      },
      "discount": {
        "id": "dis_ghi789",
        "code": "SAVE20",
        "type": "percentage",
        "value": 20
      },
      "post_purchase": {
        "files": [],
        "licenses": [],
        "courses": []
      }
    },
    "payment": {
      "checkout_url": "https://payment.example.com/checkout?token=abc123",
      "transaction_id": "txn_xyz789abc"
    }
  }
}
Initiates a new checkout session for purchasing a product. Creates a sale record and either returns a payment checkout URL for paid products or completes the sale immediately for free products.
Pay-what-you-want products are not supported via the Public API. For these products, redirect customers to your Chariow store or use the Snap Widget embed on your website.
All sales initiated via this API endpoint 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.

​
Repeat Purchases

The ability to purchase a product multiple times depends on the product type:
Product TypeRepeat PurchaseBehaviour
ServiceAlways allowedCustomers can purchase service products unlimited times. Ideal for consultations, memberships, or recurring services.
LicenseAlways allowedCustomers can purchase license products multiple times. Each purchase generates a new unique license key.
DownloadableBlockedReturns already_purchased if customer has an active access grant.
CourseBlockedReturns already_purchased if customer has an active access grant.
BundleBlockedReturns 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.

​
Authentication

This endpoint requires API key authentication via Bearer token: 
Authorization: Bearer sk_live_your_api_key

​
Request Body

​
product_id
string
required
The product public ID or slug to purchase. Example: prd_abc123xyz or premium-course
​
email
string
required
Customer email address. Must be a valid email (max 255 characters). Example: [email protected]
​
first_name
string
required
Customer first name (max 50 characters). Example: John
​
last_name
string
required
Customer last name (max 50 characters). Example: Doe
​
phone
object
required
Customer phone details
​
discount_code
string
Discount code to apply (max 100 characters). Example: SAVE20
​
campaign_id
string
Campaign public ID or tracking code for analytics. Example: camp_xyz789
​
custom_fields
object
Custom field values for the product (key-value pairs). Must match the product’s configured custom fields.
​
payment_currency
string
Currency code for payment (ISO 4217). Defaults to store currency if not provided. Example: USD, EUR, GBP
​
redirect_url
string
Custom URL to redirect customers after payment completion (max 2048 characters). When provided, customers will be redirected to this URL instead of the default Chariow post-purchase page. Must be a valid active URL. Example: https://yoursite.com/thank-you
​
custom_metadata
object
Custom key-value metadata to store with the sale. Maximum 10 keys allowed, each value limited to 255 characters. This metadata is included in Pulse webhook payloads, making it useful for linking sales with external systems. Example: {"order_ref": "ORD-123", "source": "landing_page"}

​
Shipping Address Fields

The following fields are required when the product has “Require shipping address” enabled. If shipping is not required for the product, these fields are ignored.
​
address
string
Customer street address for shipping (max 255 characters). Example: 123 Main Street
​
city
string
Customer city for shipping (max 100 characters). Example: New York
​
state
string
Customer state or region for shipping (max 100 characters). Example: NY
​
country
string
Customer country for shipping (ISO 3166-1 alpha-2 code, max 2 characters). Example: US
​
zip
string
Customer postal/ZIP code for shipping (max 20 characters). Example: 10001

​
Response

​
data
object
The checkout response object containing step, purchase, and payment information

​
Error Responses

​
401 Unauthorised
Invalid or missing API key
​
404 Not Found
Product not found or not published
​
422 Unprocessable Entity
Validation errors or pay-what-you-want product
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": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "number": "1234567890",
      "country_code": "US"
    },
    "discount_code": "SAVE20",
    "redirect_url": "https://yoursite.com/thank-you",
    "custom_metadata": {
      "order_ref": "ORD-123",
      "source": "landing_page"
    }
  }'

{
  "data": {
    "step": "awaiting_payment",
    "message": null,
    "purchase": {
      "id": "sal_abc123xyz",
      "status": "awaiting_payment",
      "original_amount": {
        "amount": 9900,
        "currency": "USD",
        "formatted": "$99.00"
      },
      "amount": {
        "amount": 7920,
        "currency": "USD",
        "formatted": "$79.20"
      },
      "discount_amount": {
        "amount": 1980,
        "currency": "USD",
        "formatted": "$19.80"
      },
      "payment": {
        "amount": {
          "amount": 7920,
          "currency": "USD",
          "formatted": "$79.20"
        },
        "status": "awaiting_payment",
        "exchange_rate": {
          "amount": 100,
          "currency": "USD",
          "formatted": "$1.00"
        }
      },
      "store": {
        "id": "str_xyz789",
        "name": "My Store"
      },
      "product": {
        "id": "prd_abc123xyz",
        "name": "Premium Course",
        "slug": "premium-course"
      },
      "customer": {
        "id": "cus_def456",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe"
      },
      "discount": {
        "id": "dis_ghi789",
        "code": "SAVE20",
        "type": "percentage",
        "value": 20
      },
      "post_purchase": {
        "files": [],
        "licenses": [],
        "courses": []
      }
    },
    "payment": {
      "checkout_url": "https://payment.example.com/checkout?token=abc123",
      "transaction_id": "txn_xyz789abc"
    }
  }
}