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 and shipping information.

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/...signed-invoice-url...",
  "payment": {
    "status": "success",
    "transaction_id": "txn_xyz789",
    "gateway": "orqex",
    "method": {
      "name": "Orange Money Senegal",
      "icon_url": "https://assets.example.com/icons/orange_money.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",
    "phone": {
      "number": "+1 234 567 890",
      "country": {
        "name": "United States",
        "code": "US",
        "alpha_3_code": "USA",
        "dial_code": "+1",
        "currency": "USD",
        "flag": "🇺🇸"
      }
    },
    "avatar_url": null
  },
  "buyer": {
    "first_name": "John",
    "last_name": "Doe"
  },
  "discount": {
    "id": "dis_jkl012",
    "name": "Save 20%",
    "code": "SAVE20"
  },
  "is_access_revoked": false,
  "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, whilst the single sale endpoint returns the full detailed object shown above. See the Listing Sales and Getting a Single Sale sections for the differences. buyer keeps the name entered at purchase time, whereas customer reflects the customer’s current profile. A gift object (recipient, message) is added for gift purchases.

Sale Statuses

Sales can have the following statuses throughout their lifecycle:

Status	Description
`initiated`	Sale created, payment not started yet
`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

failed and abandoned are not always final. When the payment gateway later reports that the buyer did pay (for example, a payment finished after the checkout timed out), the sale is reopened as awaiting_payment, its failed_at or abandoned_at is cleared, and it then moves to completed. Listen for sale events through Pulses rather than treating these statuses as definitive.

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 (1 to 100, default 10)
`cursor`	string	Cursor for pagination (from `next_cursor` or `prev_cursor`)
`status`	string	Filter by sale status (`initiated`, `awaiting_payment`, `completed`, `failed`, `abandoned`, `settled`)
`customer_id`	string	Filter by customer public ID (e.g., `cus_abc123xyz`)
`search`	string	Search by sale ID or payment transaction ID
`from`	string	Sales created on or after this date (format: `Y-m-d`, e.g., `2025-01-01`)
`to`	string	Sales created on or before this date (format: `Y-m-d`, e.g., `2025-01-31`)
`period`	string	Date range shortcut used instead of `from` and `to`: `today`, `yesterday`, `last7days`, `last30days`, `thisWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `thisYear`, `lastYear`

start_date and end_date are not supported and are silently ignored, which returns sales of every date. Use from and to.

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?from=2025-01-01&to=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"

Searching Sales

# Search by sale ID or payment transaction ID
curl -X GET "https://api.chariow.com/v1/sales?search=sal_abc123xyz" \
  -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",
      "tracking": {
        "event_id": "sal_abc123xyz",
        "currency": "USD",
        "value": 79.2
      },
      "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/...signed-invoice-url...",
      "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",
        "phone": {
          "number": "+1 234 567 890",
          "country": {
            "name": "United States",
            "code": "US",
            "alpha_3_code": "USA",
            "dial_code": "+1",
            "currency": "USD",
            "flag": "🇺🇸"
          }
        },
        "avatar_url": null
      },
      "buyer": {
        "first_name": "John",
        "last_name": "Doe"
      },
      "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"
      }
    }
  ],
  "pagination": {
    "per_page": 10,
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": null,
    "has_more_pages": 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();

Common Use Cases

Revenue Reporting

Calculate total revenue for a specific period:

const response = await fetch(
  'https://api.chariow.com/v1/sales?status=completed&from=2025-01-01&to=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.code} (${sale.payment.failure_error.customer_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&from=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

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

​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

Common Use Cases

Settlement Information

Download Tracking

Related Resources