> ## Documentation Index
> Fetch the complete documentation index at: https://chariow.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sales

> Learn how to retrieve and manage sales data via the Chariow API

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:

```json theme={null}
{
  "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"
}
```

<Note>
  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](#listing-sales) and [Getting a Single Sale](#getting-a-single-sale) sections for the differences.
</Note>

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/sales" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

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

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

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

  sales = response.json()['data']
  ```
</CodeGroup>

### 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```javascript theme={null}
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:

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/sales/sal_abc123" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

## 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:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Revenue Reporting" icon="chart-line">
    Calculate total revenue for a specific period:

    ```javascript theme={null}
    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}`);
    ```
  </Accordion>

  <Accordion title="Order Fulfilment" icon="truck">
    Process orders that require physical shipping:

    ```javascript theme={null}
    // 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}`);
    });
    ```
  </Accordion>

  <Accordion title="Customer Purchase History" icon="clock-rotate-left">
    View a customer's complete purchase history:

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="Failed Payment Recovery" icon="credit-card">
    Identify and process failed payments:

    ```javascript theme={null}
    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
      }
    });
    ```
  </Accordion>

  <Accordion title="Discount Performance Analysis" icon="tag">
    Analyse discount code usage and effectiveness:

    ```javascript theme={null}
    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);
    ```
  </Accordion>
</AccordionGroup>

## Settlement Information

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

## Related Resources

<CardGroup cols={2}>
  <Card title="Checkout Guide" icon="shopping-cart" href="/en/guides/checkout">
    Learn how to create sales
  </Card>

  <Card title="Pulses" icon="webhook" href="/en/guides/pulses">
    Get notified of new sales
  </Card>

  <Card title="Sales API" icon="code" href="/api-reference/sales/list-sales">
    View the complete Sales API reference
  </Card>
</CardGroup>