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

A sale 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": {
    "amount": 9900,
    "currency": "USD",
    "formatted": "$99.00"
  },
  "amount": {
    "amount": 7920,
    "currency": "USD",
    "formatted": "$79.20"
  },
  "discount_amount": {
    "amount": 1980,
    "currency": "USD",
    "formatted": "$19.80"
  },
  "settlement": {
    "amount": {
      "amount": 7524,
      "currency": "USD",
      "formatted": "$75.24"
    },
    "due_at": "2025-02-01T00:00:00+00:00",
    "done_at": "2025-02-01T10:15:00+00:00",
    "service_fee": {
      "amount": 396,
      "currency": "USD",
      "formatted": "$3.96"
    }
  },
  "download": {
    "total": 3,
    "last_at": "2025-01-20T14:30:00+00:00"
  },
  "payment": {
    "status": "success",
    "transaction_id": "txn_moneroo_xyz789",
    "gateway": "moneroo",
    "method": {
      "id": "card",
      "name": "Credit/Debit Card"
    },
    "amount": {
      "amount": 7920,
      "currency": "USD",
      "formatted": "$79.20"
    },
    "fee": {
      "amount": 237,
      "currency": "USD",
      "formatted": "$2.37"
    },
    "exchange_rate": {
      "amount": 1.0,
      "currency": "USD",
      "formatted": "$1.00"
    }
  },
  "shipping": {
    "address": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "country": {
      "code": "US",
      "name": "United States"
    },
    "zip": "10001"
  },
  "context": {
    "ip_address": "203.0.113.42",
    "country": {
      "code": "US",
      "name": "United States"
    },
    "device_type": "desktop",
    "locale": "en_US"
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "slug": "my-digital-store"
  },
  "product": {
    "id": "prd_def456",
    "name": "Premium Course",
    "type": "course"
  },
  "customer": {
    "id": "cus_ghi789",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "discount": {
    "id": "dis_jkl012",
    "code": "SAVE20",
    "type": "percentage"
  },
  "rate": {
    "id": "rat_mno345",
    "value": 5,
    "comment": "Excellent product!"
  },
  "campaign": {
    "id": "cmp_pqr678",
    "name": "Black Friday Campaign"
  },
  "post_purchase": {
    "files": [
      {
        "id": "fil_stu901",
        "name": "course-materials.zip",
        "download_url": "https://cdn.chariow.com/..."
      }
    ],
    "licences": [],
    "instructions": "Thank you for your purchase!"
  },
  "created_at": "2025-01-15T10:30:00+00:00",
  "completed_at": "2025-01-15T10:32:00+00:00"
}

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"

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/[email protected]" \
  -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

{
  "data": [
    {
      "id": "sal_abc123xyz",
      "status": "completed",
      "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": {
        "status": "success",
        "amount": {
          "amount": 7920,
          "currency": "USD",
          "formatted": "$79.20"
        }
      },
      "customer": {
        "id": "cus_xyz789",
        "email": "[email protected]",
        "name": "John Doe"
      },
      "product": {
        "id": "prd_def456",
        "name": "Premium Course",
        "type": "course"
      },
      "store": {
        "id": "str_ghi789",
        "name": "My Digital Store"
      },
      "discount": {
        "id": "dis_jkl012",
        "code": "SAVE20"
      }
    }
  ],
  "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"

Post-Purchase Access

Completed sales include post-purchase access data containing deliverables based on the product type:

{
  "post_purchase": {
    "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.amount,
  0
);

console.log(`Total revenue: ${totalRevenue / 100}`); // Convert from smallest unit

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.amount;
    acc[code].discountGiven += sale.discount_amount.amount;
    return acc;
  }, {});

console.log(discountStats);

Settlement Information

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

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

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

Resources

MCP Integration

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 Access

File Downloads

Licences

Custom Instructions

Common Use Cases

Settlement Information

Download Tracking

Checkout Guide

Pulses

Sales API

Introduction

Guides

Resources

MCP Integration

​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 Access

​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 Access

File Downloads

Licences

Custom Instructions

Common Use Cases

Settlement Information

Download Tracking

Related Resources