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

# List Sales

> Retrieve all sales from your store

Retrieves a cursor-paginated list of all sales in your store. Sales represent completed, pending, abandoned, failed, or settled transactions. The response includes customer, product, discount, and rating information.

## Query Parameters

<ParamField query="per_page" type="integer" default="15">
  Number of sales to return per page (max 100)
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for pagination. Use the `next_cursor` from the previous response.
</ParamField>

<ParamField query="status" type="string">
  Filter by sale status: `awaiting_payment`, `completed`, `failed`, `abandoned`, or `settled`
</ParamField>

<ParamField query="customer_id" type="string">
  Filter by customer public ID (e.g., `cus_abc123xyz`)
</ParamField>

<ParamField query="search" type="string">
  Search by sale reference or customer email
</ParamField>

<ParamField query="start_date" type="string">
  Filter sales from this date onwards (format: `Y-m-d`, e.g., `2025-01-01`)
</ParamField>

<ParamField query="end_date" type="string">
  Filter sales until this date (format: `Y-m-d`, e.g., `2025-01-31`)
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of sale objects

  <Expandable title="sale object">
    <ResponseField name="id" type="string">
      Unique sale identifier (e.g., `sal_abc123xyz`)
    </ResponseField>

    <ResponseField name="status" type="string">
      Sale status (`awaiting_payment`, `completed`, `failed`, `abandoned`, `settled`)
    </ResponseField>

    <ResponseField name="original_amount" type="object">
      Original amount before discount

      <Expandable title="amount object">
        <ResponseField name="value" type="integer">
          Amount value (e.g., 99 for \$99.00)
        </ResponseField>

        <ResponseField name="formatted" type="string">
          Formatted amount with currency symbol (e.g., `$99.00`)
        </ResponseField>

        <ResponseField name="short" type="string">
          Short formatted amount (e.g., `$99`)
        </ResponseField>

        <ResponseField name="currency" type="string">
          Three-letter ISO currency code (e.g., `USD`, `EUR`)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="amount" type="object">
      Final amount charged after discount
    </ResponseField>

    <ResponseField name="discount_amount" type="object">
      Discount amount applied
    </ResponseField>

    <ResponseField name="payment" type="object">
      Payment details

      <Expandable title="payment object">
        <ResponseField name="amount" type="object">
          Amount paid in payment currency
        </ResponseField>

        <ResponseField name="status" type="string">
          Payment status (`initiated`, `pending`, `cancelled`, `failed`, `success`)
        </ResponseField>

        <ResponseField name="exchange_rate" type="object">
          Exchange rate if multi-currency
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="shipping" type="object">
      Shipping address details (if provided)

      <Expandable title="shipping object">
        <ResponseField name="address" type="string">
          Street address
        </ResponseField>

        <ResponseField name="city" type="string">
          City name
        </ResponseField>

        <ResponseField name="state" type="string">
          State or province
        </ResponseField>

        <ResponseField name="country" type="string">
          Country code
        </ResponseField>

        <ResponseField name="zip" type="string">
          Postal/ZIP code
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="store" type="object">
      Store information
    </ResponseField>

    <ResponseField name="product" type="object">
      Product information
    </ResponseField>

    <ResponseField name="customer" type="object">
      Customer information
    </ResponseField>

    <ResponseField name="discount" type="object">
      Applied discount (if any)
    </ResponseField>

    <ResponseField name="rate" type="object">
      Customer rating (if provided)
    </ResponseField>

    <ResponseField name="post_purchase" type="object">
      Post-purchase access data (files, licences, instructions)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata

  <Expandable title="pagination object">
    <ResponseField name="next_cursor" type="string">
      Cursor for next page (null if no more pages)
    </ResponseField>

    <ResponseField name="prev_cursor" type="string">
      Cursor for previous page (null if first page)
    </ResponseField>

    <ResponseField name="has_more" type="boolean">
      Whether more results are available
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/sales?status=completed&per_page=20&start_date=2025-01-01" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.chariow.com/v1/sales?status=completed&per_page=20&start_date=2025-01-01', {
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key'
    }
  });
  const result = await response.json();
  console.log(result.data); // Array of sales
  console.log(result.pagination); // Pagination info
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.chariow.com/v1/sales?status=completed&per_page=20&start_date=2025-01-01');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer sk_live_your_api_key'
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  $data = json_decode($response, true);
  ```

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

  response = requests.get(
      'https://api.chariow.com/v1/sales',
      params={
          'status': 'completed',
          'per_page': 20,
          'start_date': '2025-01-01'
      },
      headers={'Authorization': 'Bearer sk_live_your_api_key'}
  )

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

<ResponseExample>
  ```json Response theme={null}
  {
    "message": "success",
    "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"
          }
        },
        "shipping": {
          "address": "123 Main Street",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "zip": "10001"
        },
        "store": {
          "id": "str_xyz789",
          "name": "My Store",
          "slug": "my-store"
        },
        "product": {
          "id": "prd_def456",
          "name": "Premium Course",
          "type": "course"
        },
        "customer": {
          "id": "cus_ghi789",
          "email": "customer@example.com",
          "name": "John Doe"
        },
        "discount": {
          "id": "dis_jkl012",
          "code": "SAVE20",
          "type": "percentage"
        },
        "rate": null,
        "post_purchase": {
          "files": [
            {
              "id": "fil_mno345",
              "name": "course-materials.zip",
              "size": 15728640,
              "download_url": "https://cdn.chariow.com/downloads/..."
            }
          ],
          "licences": [],
          "instructions": "Thank you for your purchase!"
        }
      }
    ],
    "pagination": {
      "next_cursor": "eyJpZCI6NTB9",
      "prev_cursor": null,
      "has_more": true
    },
    "errors": []
  }
  ```
</ResponseExample>