Sales

Sales represent purchase transactions in your store, whether completed, pending, abandoned, failed, or settled. Each sale contains comprehensive information about the product, customer, payment details, applied discounts, shipping information, and post-purchase access.

Understanding Sales

The Chariow Sales API provides programmatic access to all transaction data in your store. You can:

Retrieve a list of all sales with filtering options
Get detailed information about specific sales
Track payment status and settlement details
Access customer purchase history
Monitor download statistics
View applied discounts and marketing campaigns

Sale Object

The detailed sale object (returned by the single sale endpoint) contains comprehensive purchase information with the following structure:

{
  "id": "sal_abc123xyz",
  "status": "completed",
  "channel": {
    "value": "store",
    "label": "Store",
    "description": "Sale made through the store checkout"
  },
  "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"
  },
  "settlement": {
    "amount": {
      "value": 75.24,
      "formatted": "$75.24",
      "short": "75",
      "currency": "USD"
    },
    "due_at": "2025-02-01T00:00:00+00:00",
    "done_at": "2025-02-01T10:15:00+00:00",
    "service_fee": {
      "value": 3.96,
      "formatted": "$3.96",
      "short": "4",
      "currency": "USD"
    }
  },
  "download": {
    "total": 3,
    "last_at": "2025-01-20T14:30:00+00:00"
  },
  "invoice_download_url": "https://api.chariow.com/invoices/sal_abc123xyz.pdf",
  "payment": {
    "status": "success",
    "transaction_id": "txn_moneroo_xyz789",
    "gateway": "moneroo",
    "method": {
      "name": "Credit/Debit Card",
      "icon_url": "https://assets.cdn.moneroo.io/icons/circle/card.svg"
    },
    "amount": {
      "value": 79.20,
      "formatted": "$79.20",
      "short": "79",
      "currency": "USD"
    },
    "fee": {
      "value": 2.37,
      "formatted": "$2.37",
      "short": "2",
      "currency": "USD"
    },
    "fee_rate": "3%",
    "interchange": {
      "rate": "1.5%",
      "fee": {
        "value": 1.19,
        "formatted": "$1.19",
        "short": "1",
        "currency": "USD"
      }
    },
    "exchange_rate": {
      "value": 1.0,
      "formatted": "$1.00",
      "short": "1",
      "currency": "USD"
    },
    "failure_error": null
  },
  "shipping": {
    "address": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "country": {
      "name": "United States",
      "code": "US",
      "alpha_3_code": "USA",
      "dial_code": "+1",
      "currency": "USD",
      "flag": "🇺🇸"
    },
    "zip": "10001"
  },
  "context": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "ip_address": "203.0.113.42",
    "country": {
      "name": "United States",
      "code": "US",
      "alpha_3_code": "USA",
      "dial_code": "+1",
      "currency": "USD",
      "flag": "🇺🇸"
    },
    "device_type": "desktop",
    "locale": "en_US"
  },
  "custom_fields_values": null,
  "campaign": {
    "id": "cmp_pqr678",
    "name": "Black Friday Campaign"
  },
  "rating": {
    "id": "rat_mno345",
    "is_thumbs_up": true,
    "comment": "Excellent product!",
    "created_at": "2025-01-18T09:00:00+00:00"
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
    "url": "https://mystore.mychariow.com"
  },
  "product": {
    "id": "prd_def456",
    "name": "Premium Course",
    "type": "course",
    "pictures": {
      "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
      "cover": "https://cdn.chariow.com/products/cover.jpg"
    },
    "category": {
      "value": "education_and_learning",
      "label": "Education and Learning"
    },
    "pricing": {
      "type": "one_time",
      "price": {
        "value": 99,
        "formatted": "$99.00",
        "short": "99",
        "currency": "USD"
      },
      "effective": {
        "value": 79.20,
        "formatted": "$79.20",
        "short": "79",
        "currency": "USD"
      }
    },
    "bundle": null,
    "metadata": null
  },
  "customer": {
    "id": "cus_ghi789",
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "email": "customer@example.com",
    "avatar_url": null
  },
  "discount": {
    "id": "dis_jkl012",
    "name": "Save 20%",
    "code": "SAVE20"
  },
  "store_affiliate": null,
  "affiliate_commission": null,
  "is_reconciled": true,
  "last_reconciled_at": "2025-02-01T10:15:00+00:00",
  "failed_at": null,
  "awaiting_payment_at": "2025-01-15T10:30:00+00:00",
  "abandoned_at": null,
  "completed_at": "2025-01-15T10:32:00+00:00",
  "created_at": "2025-01-15T10:30:00+00:00",
  "updated_at": "2025-01-15T10:32:00+00:00"
}

The list endpoint returns a simplified version of the sale object (using SalePublicResource), whilst the single sale endpoint returns the full detailed object (using SaleResource). See the Listing Sales and Getting a Single Sale sections for the differences.

Sale Statuses

Sales can have the following statuses throughout their lifecycle:

Status	Description
`awaiting_payment`	Checkout initiated, waiting for payment confirmation
`completed`	Payment successful, product access granted to customer
`failed`	Payment failed or was declined
`abandoned`	Customer abandoned the checkout process
`settled`	Funds have been settled to the merchant account

Payment Statuses

The payment status tracks the payment gateway transaction separately from the sale status:

Payment Status	Description
`initiated`	Payment process has started
`pending`	Payment is being processed by the gateway
`success`	Payment was successfully processed
`failed`	Payment failed or was declined
`cancelled`	Payment was cancelled by customer or system

Sales Channels

Sales can originate from different channels:

Channel	Description
`store`	Direct sale through your store checkout
`affiliate`	Sale made through an affiliate link
`discover`	Sale from Chariow Discover marketplace
`widget`	Sale through an embedded checkout widget
`api`	Sale created via the Public API

Listing Sales

Retrieve all sales for your store:

curl -X GET "https://api.chariow.com/v1/sales" \
  -H "Authorization: Bearer sk_live_your_api_key"

const response = await fetch('https://api.chariow.com/v1/sales', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const result = await response.json();

import requests

response = requests.get(
    'https://api.chariow.com/v1/sales',
    headers={'Authorization': 'Bearer sk_live_your_api_key'}
)

sales = response.json()['data']

Query Parameters

You can filter and paginate sales using the following parameters:

Parameter	Type	Description
`per_page`	integer	Number of sales per page (max 100, default 15)
`cursor`	string	Cursor for pagination (from `next_cursor` or `prev_cursor`)
`status`	string	Filter by sale status (`awaiting_payment`, `completed`, `failed`, `abandoned`, `settled`)
`customer_id`	string	Filter by customer public ID (e.g., `cus_abc123xyz`)
`search`	string	Search by sale reference or customer email
`start_date`	string	Filter sales from this date (format: `Y-m-d`, e.g., `2025-01-01`)
`end_date`	string	Filter sales until this date (format: `Y-m-d`, e.g., `2025-01-31`)

Filtering by Status

# Get only completed sales
curl -X GET "https://api.chariow.com/v1/sales?status=completed" \
  -H "Authorization: Bearer sk_live_your_api_key"

Filtering by Customer

# Get sales for a specific customer
curl -X GET "https://api.chariow.com/v1/sales?customer_id=cus_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

Filtering by Date Range

# Get sales from January 2025
curl -X GET "https://api.chariow.com/v1/sales?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"

Searching Sales

# Search by customer email or sale reference
curl -X GET "https://api.chariow.com/v1/sales?search=customer@example.com" \
  -H "Authorization: Bearer sk_live_your_api_key"

Pagination

The API uses cursor-based pagination. Use the next_cursor from the response to fetch the next page:

let cursor = null;
let allSales = [];

do {
  const url = cursor
    ? `https://api.chariow.com/v1/sales?cursor=${cursor}`
    : 'https://api.chariow.com/v1/sales';

  const response = await fetch(url, {
    headers: { 'Authorization': 'Bearer sk_live_your_api_key' }
  });

  const result = await response.json();
  allSales = [...allSales, ...result.data];
  cursor = result.pagination.next_cursor;
} while (cursor);

Example Response

The list endpoint returns a simplified sale object per item:

{
  "data": [
    {
      "id": "sal_abc123xyz",
      "status": "completed",
      "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"
      },
      "payment": {
        "amount": {
          "value": 79.20,
          "formatted": "$79.20",
          "short": "79",
          "currency": "USD"
        },
        "status": "success",
        "exchange_rate": {
          "value": 1.0,
          "formatted": "$1.00",
          "short": "1",
          "currency": "USD"
        },
        "failure_error": null
      },
      "shipping": {
        "address": "123 Main Street",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "zip": "10001"
      },
      "invoice_download_url": "https://api.chariow.com/invoices/sal_abc123xyz.pdf",
      "created_at": "2025-01-15T10:30:00+00:00",
      "completed_at": "2025-01-15T10:32:00+00:00",
      "store": {
        "id": "str_ghi789",
        "name": "My Digital Store",
        "logo_url": "https://cdn.chariow.com/stores/ghi789/logo.png",
        "url": "https://mystore.mychariow.com"
      },
      "product": {
        "id": "prd_def456",
        "name": "Premium Course",
        "type": "course",
        "pictures": {
          "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
          "cover": "https://cdn.chariow.com/products/cover.jpg"
        },
        "category": {
          "value": "education_and_learning",
          "label": "Education and Learning"
        },
        "pricing": {
          "type": "one_time",
          "price": {
            "value": 99,
            "formatted": "$99.00",
            "short": "99",
            "currency": "USD"
          },
          "effective": {
            "value": 79.20,
            "formatted": "$79.20",
            "short": "79",
            "currency": "USD"
          }
        },
        "bundle": null,
        "metadata": null
      },
      "customer": {
        "id": "cus_xyz789",
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "email": "customer@example.com",
        "avatar_url": null
      },
      "discount": {
        "id": "dis_jkl012",
        "name": "Save 20%",
        "code": "SAVE20"
      },
      "rate": {
        "id": "rat_mno345",
        "is_thumbs_up": true,
        "comment": "Excellent product!",
        "created_at": "2025-01-18T09:00:00+00:00"
      },
      "fulfillment": null
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": null,
    "has_more": true
  }
}

Getting a Single Sale

Retrieve a specific sale by its public ID:

curl -X GET "https://api.chariow.com/v1/sales/sal_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

const response = await fetch('https://api.chariow.com/v1/sales/sal_abc123', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const result = await response.json();

Post-Purchase Fulfillment

Completed sales can include fulfillment data containing deliverables based on the product type. The fulfillment field is present in the list endpoint response when populated:

{
  "fulfillment": {
    "files": [
      {
        "id": "fil_abc123",
        "name": "course-materials.zip",
        "size": 15728640,
        "type": "application/zip",
        "download_url": "https://cdn.chariow.com/downloads/...",
        "expires_at": "2025-01-20T10:30:00+00:00"
      }
    ],
    "licences": [
      {
        "id": "lic_def456",
        "licence_key": "ABC-123-XYZ-789",
        "status": "active",
        "activations": 2,
        "max_activations": 5,
        "expires_at": null
      }
    ],
    "instructions": "Thank you for your purchase! Here's how to get started with your course materials..."
  }
}

File Downloads

For products with downloadable files, the files array contains:

id - Unique file identifier
name - Original filename
size - File size in bytes
type - MIME type
download_url - Temporary signed download URL
expires_at - When the download link expires

Licences

For products with licence keys, the licences array contains:

id - Unique licence identifier
licence_key - The licence key string
status - Licence status (active, inactive, expired)
activations - Current number of activations
max_activations - Maximum allowed activations
expires_at - Expiry date (null for lifetime licences)

Custom Instructions

The instructions field contains custom post-purchase instructions configured for the product.

Common Use Cases

Revenue Reporting

Calculate total revenue for a specific period:

const response = await fetch(
  'https://api.chariow.com/v1/sales?status=completed&start_date=2025-01-01&end_date=2025-01-31',
  { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
);

const result = await response.json();
const totalRevenue = result.data.reduce(
  (sum, sale) => sum + sale.amount.value,
  0
);

console.log(`Total revenue: ${totalRevenue}`);

Order Fulfilment

Process orders that require physical shipping:

// Get completed sales with shipping addresses
const response = await fetch(
  'https://api.chariow.com/v1/sales?status=completed',
  { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
);

const result = await response.json();
const ordersToShip = result.data.filter(
  sale => sale.shipping && sale.shipping.address
);

// Process each order
ordersToShip.forEach(sale => {
  console.log(`Ship to: ${sale.shipping.address}, ${sale.shipping.city}`);
});

Customer Purchase History

View a customer’s complete purchase history:

curl -X GET "https://api.chariow.com/v1/sales?customer_id=cus_abc123xyz" \
  -H "Authorization: Bearer sk_live_your_api_key"

This returns all sales for the specified customer, including:

Purchase dates and amounts
Products purchased
Applied discounts
Current access status

Failed Payment Recovery

Identify and process failed payments:

const response = await fetch(
  'https://api.chariow.com/v1/sales?status=failed',
  { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
);

const result = await response.json();

// Review failed sales and payment error details
result.data.forEach(sale => {
  if (sale.payment.failure_error) {
    console.log(`Failed sale ${sale.id}: ${sale.payment.failure_error.message}`);
    // Take action based on error code
  }
});

Discount Performance Analysis

Analyse discount code usage and effectiveness:

const response = await fetch(
  'https://api.chariow.com/v1/sales?status=completed&start_date=2025-01-01',
  { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
);

const result = await response.json();

// Group by discount code
const discountStats = result.data
  .filter(sale => sale.discount)
  .reduce((acc, sale) => {
    const code = sale.discount.code;
    if (!acc[code]) {
      acc[code] = { uses: 0, revenue: 0, discountGiven: 0 };
    }
    acc[code].uses++;
    acc[code].revenue += sale.amount.value;
    acc[code].discountGiven += sale.discount_amount.value;
    return acc;
  }, {});

console.log(discountStats);

Settlement Information

For completed sales, the settlement object provides details about merchant payouts:

{
  "settlement": {
    "amount": {
      "value": 75.24,
      "formatted": "$75.24",
      "short": "75",
      "currency": "USD"
    },
    "due_at": "2025-02-01T00:00:00+00:00",
    "done_at": "2025-02-01T10:15:00+00:00",
    "service_fee": {
      "value": 3.96,
      "formatted": "$3.96",
      "short": "4",
      "currency": "USD"
    }
  }
}

amount - Net amount to be paid to merchant (after fees)
due_at - When settlement is scheduled
done_at - When settlement was completed (null if pending)
service_fee - Chariow platform service fee

Download Tracking

Monitor customer download activity:

{
  "download": {
    "total": 3,
    "last_at": "2025-01-20T14:30:00+00:00"
  }
}

This helps you:

Track product engagement
Identify customers who haven’t accessed their purchase
Monitor for unusual download patterns

Checkout Guide

Learn how to create sales

Pulses

Get notified of new sales

Sales API

View the complete Sales API reference

Introduction

Guides

MCP Integration

n8n Integration

Resources

Understanding Sales

Sale Object

Sale Statuses

Payment Statuses

Sales Channels

Listing Sales

Query Parameters

Filtering by Status

Filtering by Customer

Filtering by Date Range

Searching Sales

Example Response

Getting a Single Sale

Post-Purchase Fulfillment

File Downloads

Licences

Custom Instructions

Common Use Cases

Settlement Information

Download Tracking

Checkout Guide

Pulses

Sales API

​Understanding Sales

​Sale Object

​Sale Statuses

​Payment Statuses

​Sales Channels

​Listing Sales

​Query Parameters

​Filtering by Status

​Filtering by Customer

​Filtering by Date Range

​Searching Sales

​Pagination

​Example Response

​Getting a Single Sale

​Post-Purchase Fulfillment

​File Downloads

​Licences

​Custom Instructions

​Common Use Cases

​Settlement Information

​Download Tracking

​Related Resources

Checkout Guide

Pulses

Sales API

Understanding Sales

Sale Object

Sale Statuses

Payment Statuses

Sales Channels

Listing Sales

Query Parameters

Filtering by Status

Filtering by Customer

Filtering by Date Range

Searching Sales

Pagination

Example Response

Getting a Single Sale

Post-Purchase Fulfillment

File Downloads

Licences

Custom Instructions

Common Use Cases

Settlement Information

Download Tracking

Related Resources