Campaign Statistics API (Beta)

The Campaign Statistics API allows you to retrieve detailed statistics for multiple campaigns within Custobar. This data can be used to feed external tools such as PowerBI for in-depth analysis. The API is currently in active development and subject to change.

Base URL

GET /api/beta/campaigns/

Authentication

This API uses token-based authentication. For instructions on how to obtain a token, see the API Authentication documentation.

- headers:
- Authorization: Bearer <token>

Query Parameters

• sales_start & sales_end: dates for the start and end of sales statistics in the returned data, currently also controls the range of campaign statistics for automations.
  • Format: yyyy-mm-dd.
  • Defaults: 30 days ago to now.
• limit: how many campaigns in a response.
  • Format: integer.
  • Default: 30.
• order: ordering by date.
  • Format: must be "descending" or "ascending".
  • Default: descending
• from: paging control, you may use the value of the parameter `next` returned in any previous request to this endpoint.

Response Format

The response contains paging information and a list of campaign objects.

Response Example

{

    “order”: ”descending”

  “limit”: ”30”

    “campaigns”: [
        {
            “campaign_key”: “EMAIL-A-123”,
            “kind”: “automated-email”,
            “name”: “Welcome email”,
            “state”: “active”,
            “folder”: {
                “id”: 123,
                “name”: “Welcome emails”
            },
            “permissions”: {
                “marketing_permission”: “push_marketing_permission”
            },
            “stats”: {
                “date_range”: {
                    “start”: “2024-06-01”,
                    “end”: “2024-06-31”
                },
                “audience_size”: 123,
                “audience_with_events”: 123,
                “audience_with_sales”: 123,
                “sales_for_conversion”: 123,
                “events”: [
                    { “name”: “sent”, “count”: 123 },
                    { “name”: “delivered”, “count”: 123 },
                    { “name”: “opens”, “count”: 123 },
                    { “name”: “clicks”, “count”: 123 },
                    { “name”: “unsubscribes”, “count”: 123 },
                    { “name”: “spam_reports”, “count”: 123 },
                    { “name”: “bounces”, “count”: 123 }
                ],
                “sales”: {
                    “date_range”: {
                        “start”: “2024-06-01”,
                        “end”: “2024-06-31”
                    },
                    “total_sales”: 123,
                    “total_revenue”: 123,
                    “average_products_count”: 123,
                    “total_products_count”: 123,
                    “campaign_product_count”: 123,
                    “campaign_product_revenue”: 123,
                    “other_product_count”: 123,
                    “other_product_revenue”: 123,
                    “product_categories”: [
                        {
                            “discount”: 0,
                            “revenue”: 599.0,
                            “title”: “Category C”,
                            “units”: 5.0
                        }
                    ]
                },
                “cache_modified_at”: “2024-06-31T12:00:00Z”
            }
        }
    ],
    “next”: “i1976”
}

Paging

By default, the API returns a maximum of 30 campaigns per request, sorted by the most recent first. Use the limit, order, and from query parameters to control paging.

Notes

• Campaigns of type EXT and campaigns in draft state will not include statistics.
• Campaign statistics for the last 7 days are cached every hour, and for campaigns older than 7 days (but within 30 days), the cache is updated every 24 hours.
• The more campaigns you retrieve the slower it can be. So changing the limit from 30 (default) to 100 may have a significant impact making multiple fetches might be more reliable so systems do not timeout.